{"id":47808857,"url":"https://github.com/machinefi/trioclaw","last_synced_at":"2026-04-03T18:01:10.277Z","repository":{"id":343156561,"uuid":"1162953178","full_name":"machinefi/TrioClaw","owner":"machinefi","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-09T05:26:08.000Z","size":9378,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T10:01:55.991Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/machinefi.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":null,"dco":null,"cla":null}},"created_at":"2026-02-20T22:31:59.000Z","updated_at":"2026-03-09T05:26:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"323a5600-bcaa-44b7-8351-ce504f770360","html_url":"https://github.com/machinefi/TrioClaw","commit_stats":null,"previous_names":["machinefi/trioclaw"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/machinefi/TrioClaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinefi%2FTrioClaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinefi%2FTrioClaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinefi%2FTrioClaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinefi%2FTrioClaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/machinefi","download_url":"https://codeload.github.com/machinefi/TrioClaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinefi%2FTrioClaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31368156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":[],"created_at":"2026-04-03T18:00:30.521Z","updated_at":"2026-04-03T18:01:10.210Z","avatar_url":"https://github.com/machinefi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/trioclaw-banner-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/trioclaw-banner-light.svg\"\u003e\n    \u003cimg src=\"docs/assets/trioclaw-banner-dark.svg\" alt=\"TrioClaw — Eyes, ears, voice \u0026 hands for AI agents\" width=\"600\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  An \u003ca href=\"https://github.com/openclaw/openclaw\"\u003eOpenClaw\u003c/a\u003e node that connects cameras, microphones, speakers, and smart devices\u003cbr\u003eso your AI agent can see, hear, speak, and act in the real world.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/machinefi/trioclaw/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/machinefi/trioclaw/ci.yml?branch=main\u0026style=for-the-badge\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/machinefi/trioclaw/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/machinefi/trioclaw?include_prereleases\u0026style=for-the-badge\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/machinefi/trioclaw\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/machinefi/trioclaw?style=for-the-badge\" alt=\"Go Report\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/clawd\"\u003e\u003cimg src=\"https://img.shields.io/discord/1456350064065904867?label=Discord\u0026logo=discord\u0026logoColor=white\u0026color=5865F2\u0026style=for-the-badge\" alt=\"Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e ·\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e ·\n  \u003ca href=\"#http-api\"\u003eHTTP API\u003c/a\u003e ·\n  \u003ca href=\"DESIGN.md\"\u003eDesign Doc\u003c/a\u003e ·\n  \u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e ·\n  \u003ca href=\"https://discord.gg/clawd\"\u003eDiscord\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What It Does\n\nTrioClaw is a single Go binary that gives AI agents physical senses:\n\n```\nCamera  ──→ trio-core (VLM) ──→ \"I see a delivery person\"\n                                  ├─→ Telegram / Slack / Webhook notification\n                                  ├─→ Save video clip\n                                  └─→ Push to OpenClaw Gateway\n```\n\nIt continuously monitors cameras via [trio-core](https://trio.machinefi.com) (a vision language model), detects conditions you define (\"is there a person?\", \"is the gate open?\"), and reacts — sending notifications, recording clips, generating daily digests, and forwarding alerts to AI agents.\n\n---\n\n## Quick Start\n\n```bash\n# Install\ncurl -sSL https://raw.githubusercontent.com/machinefi/TrioClaw/main/install.sh | sh\n\n# Add a camera\ntrioclaw camera add \\\n  --id front-door \\\n  --name \"Front Door\" \\\n  --source rtsp://admin:pass@192.168.1.10:554/stream \\\n  --question \"is there a person at the door?\"\n\n# Start monitoring\ntrioclaw run\n```\n\nOn first run, TrioClaw checks if trio-core is available. If not, it prompts you:\n\n```\ntrio-core is not reachable at http://localhost:8000\n\n  1) Install locally  — runs on your machine, needs Python 3.10+\n  2) Use cloud        — connects to trio.machinefi.com\n\nChoose [1/2] (default: 2):\n```\n\nOption 1 auto-detects Python and uv/pip, installs trio-core, and manages the process. Option 2 uses the hosted API with zero setup.\n\n### Standalone Mode\n\nWorks without OpenClaw — no Gateway needed:\n\n```bash\n# One-shot: snap + ask\ntrioclaw snap --analyze \"what do you see?\"\n\n# Check system health\ntrioclaw doctor\n```\n\n### With OpenClaw Gateway\n\n```bash\n# Pair with your Gateway (one-time)\ntrioclaw pair --gateway ws://192.168.1.100:18789\n\n# Start — connects to Gateway + monitors cameras\ntrioclaw run\n```\n\nThen, in OpenClaw:\n\n```\nYou:   \"What do you see on the front door camera?\"\nAgent: \"The front porch is empty.\"\n\nYou:   \"Watch for deliveries and let me know.\"\nAgent: \"I'll keep an eye on it.\"\n\n       ... 30 min later ...\n\nAgent: \"A delivery person just left a package at your front door.\"\n```\n\n---\n\n## Configuration\n\nConfig file: `~/.trioclaw/config.yaml`\n\n```yaml\ntrio_core:\n  url: http://localhost:8000     # or https://trio.machinefi.com\n\ncameras:\n  - id: front-door\n    name: Front Door\n    source: rtsp://admin:pass@192.168.1.10:554/stream\n    fps: 1\n    conditions:\n      - id: person\n        question: \"is there a person at the door?\"\n        actions: [webhook, telegram, clip]\n      - id: package\n        question: \"is there a package on the ground?\"\n        actions: [telegram]\n\n  - id: backyard\n    name: Backyard\n    source: rtsp://192.168.1.11:554/stream\n    conditions:\n      - id: animal\n        question: \"is there an animal in the yard?\"\n        actions: [slack]\n\nnotifications:\n  webhook:\n    url: https://example.com/hook\n    headers:\n      Authorization: Bearer xxx\n  telegram:\n    bot_token: \"123456:ABC-DEF\"\n    chat_id: \"-1001234567890\"\n  slack:\n    webhook_url: https://hooks.slack.com/services/T.../B.../xxx\n\nclips:\n  dir: ~/.trioclaw/clips/\n  post_seconds: 15\n\ndigest:\n  enabled: true\n  schedule: \"0 22 * * *\"     # daily at 10 PM\n  llm: local                  # local | claude | openai\n  push_to: [telegram]\n```\n\n### Condition Actions\n\nEach condition can trigger one or more actions when the VLM detects a match:\n\n| Action | What it does |\n|--------|-------------|\n| `webhook` | POST alert JSON to your webhook URL |\n| `telegram` | Send message + snapshot to Telegram chat |\n| `slack` | Send formatted message to Slack channel |\n| `clip` | Record post-alert video clip via ffmpeg |\n\n### Daily Digest\n\nWhen enabled, TrioClaw generates a daily summary of all alerts using an LLM:\n\n| LLM | Description |\n|-----|-------------|\n| `local` | Uses trio-core's `/v1/chat/completions` endpoint (default) |\n| `claude` | Uses Anthropic Claude API (set `ANTHROPIC_API_KEY`) |\n| `openai` | Uses OpenAI API (set `OPENAI_API_KEY`) |\n\nFalls back to a plain-text summary if the LLM is unavailable.\n\n---\n\n## HTTP API\n\nTrioClaw runs an HTTP API server on `:8080` (configurable with `--listen`).\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /healthz` | Health check |\n| `GET /api/status` | Service overview (cameras, watches, uptime) |\n| `GET /api/cameras` | List configured cameras (credentials masked) |\n| `GET /api/watches` | List active watch streams |\n| `GET /api/events?date=2026-03-09\u0026camera=front-door\u0026limit=100` | Query events |\n| `GET /api/alerts?date=2026-03-09\u0026camera=front-door` | Query triggered alerts |\n| `GET /api/alerts/recent?limit=20` | Most recent alerts |\n| `GET /api/stats` | Aggregate statistics |\n| `GET /api/clips/{filename}` | Serve a saved clip file |\n\n---\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `trioclaw run` | Start the service (trio-core SSE + API + Gateway) |\n| `trioclaw camera add` | Add a camera to config |\n| `trioclaw camera remove \u003cid\u003e` | Remove a camera |\n| `trioclaw camera list` | List configured cameras |\n| `trioclaw status` | Show service status and recent alerts |\n| `trioclaw snap [--analyze \"question\"]` | One-shot capture + optional VLM analysis |\n| `trioclaw pair --gateway ws://...` | Pair with an OpenClaw Gateway |\n| `trioclaw doctor` | Check dependencies and devices |\n| `trioclaw update` | Self-update to latest release |\n| `trioclaw version` | Show version info |\n\n### Run Flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--config` | `~/.trioclaw/config.yaml` | Config file path |\n| `--camera` | — | Additional camera source (repeatable) |\n| `--trio-api` | — | Override trio-core URL |\n| `--listen` | `:8080` | HTTP API listen address |\n| `--ha-url` | — | Home Assistant URL |\n| `--ha-token` | — | Home Assistant access token |\n| `--plugin-dir` | `~/.trioclaw/plugins/` | Exec plugin scripts directory |\n\n---\n\n## OpenClaw Commands\n\nWhen connected to a Gateway, TrioClaw responds to these invoke commands:\n\n| Command | Description |\n|---------|-------------|\n| `camera.snap` | Capture a JPEG frame |\n| `camera.list` | List available cameras |\n| `camera.clip` | Record a short video clip |\n| `vision.analyze` | Capture + VLM analysis (\"what do you see?\") |\n| `vision.watch` | Start continuous monitoring with conditions |\n| `vision.watch.stop` | Stop a watch stream |\n| `vision.status` | Show active watches and their state |\n| `device.list` | List available smart devices |\n| `device.control` | Send command to a smart device |\n\n---\n\n## How It Works\n\n```\n                        TrioClaw (Go)                    trio-core (Python)\n                    ┌───────────────────┐            ┌──────────────────────┐\n  User / AI ───→    │  Config Manager   │            │  RTSP capture        │\n                    │  (cameras, conds) │            │  (ffmpeg subprocess) │\n                    │        │          │            │        │             │\n                    │  Watch Manager    │──POST /v1/watch──→  │             │\n                    │  (per camera)     │            │  VLM inference       │\n                    │        │          │←──SSE stream────    │             │\n                    │        │          │            │  (Ollama / OpenAI)   │\n                    │        ├─→ SQLite │            └──────────────────────┘\n                    │        ├─→ Notify │\n                    │        │   ├─→ Webhook\n                    │        │   ├─→ Telegram\n                    │        │   └─→ Slack\n                    │        └─→ Gateway\n                    │                   │\n                    │  HTTP API (:8080) │\n                    │  Web Dashboard    │\n                    │  Plugin System    │\n                    └───────────────────┘\n```\n\n**TrioClaw does NOT touch RTSP, ffmpeg, or inference.** It is purely the application layer:\n\n1. Stores camera RTSP addresses and watch conditions in config\n2. Calls `POST /v1/watch` on trio-core, passing RTSP URL + conditions\n3. Reads the SSE event stream, stores results in SQLite, sends notifications\n4. Serves the web dashboard and REST API\n\ntrio-core handles all the heavy lifting: RTSP capture via ffmpeg, VLM inference via Ollama/OpenAI, and streaming results back over SSE.\n\n### Key Design Decisions\n\n- **Clear separation** — TrioClaw = app layer (config, storage, notifications, dashboard); trio-core = inference layer (RTSP, ffmpeg, VLM)\n- **Zero CGO** — SQLite via modernc.org/sqlite (pure Go)\n- **SSE-based monitoring** — trio-core streams results/alerts over Server-Sent Events, no polling\n- **Credential masking** — RTSP passwords are masked (`***:***@host`) in all API responses and logs\n- **Path traversal protection** — clip serving endpoint validates paths stay within clip directory\n- **Graceful shutdown** — SIGINT/SIGTERM triggers ordered cleanup of SSE streams, HTTP server, trio-core subprocess\n- **trio-core auto-management** — detects Python, installs via uv/pip, manages subprocess lifecycle\n\n---\n\n## Project Structure\n\n```\nTrioClaw/\n├── cmd/trioclaw/              # CLI: pair, run, snap, camera, status, doctor, update\n├── internal/\n│   ├── api/\n│   │   └── server.go          # HTTP REST API (/api/events, /api/alerts, etc.)\n│   ├── capture/\n│   │   ├── ffmpeg.go          # Camera capture via ffmpeg subprocess\n│   │   └── mic.go             # Microphone capture\n│   ├── clip/\n│   │   └── clip.go            # Post-alert video clip recording via ffmpeg\n│   ├── config/\n│   │   └── config.go          # YAML config loader (~/.trioclaw/config.yaml)\n│   ├── digest/\n│   │   └── digest.go          # Daily digest (local LLM / Claude / OpenAI)\n│   ├── gateway/\n│   │   ├── protocol.go        # OpenClaw WebSocket protocol v3\n│   │   ├── client.go          # WebSocket client + reconnect\n│   │   └── handler.go         # Invoke command dispatcher\n│   ├── notify/\n│   │   └── notify.go          # Notification dispatcher (webhook, telegram, slack)\n│   ├── plugin/\n│   │   ├── plugin.go          # Plugin registry\n│   │   ├── homeassistant/     # Home Assistant plugin\n│   │   └── execplugin/        # Exec script plugins\n│   ├── store/\n│   │   └── store.go           # SQLite event store (WAL mode)\n│   ├── triocore/\n│   │   ├── client.go          # trio-core SSE client\n│   │   ├── manager.go         # Watch manager (SSE per camera)\n│   │   └── setup.go           # trio-core auto-detect / install / lifecycle\n│   ├── vision/\n│   │   └── trio.go            # Trio API client (POST /check-once)\n│   └── state/\n│       └── state.go           # Persistent state (~/.trioclaw/state.json)\n├── e2e/\n│   └── smoke_test.go          # 31 smoke tests\n├── DESIGN.md\n├── SKILL.md\n├── go.mod\n└── install.sh\n```\n\n---\n\n## Supported Devices\n\n| Device | How | Platforms |\n|--------|-----|-----------|\n| Built-in webcam | `ffmpeg -f avfoundation` / `v4l2` / `dshow` | macOS, Linux, Windows |\n| USB camera | Same as webcam (auto-discovered) | All |\n| RTSP / IP camera | `ffmpeg -rtsp_transport tcp -i rtsp://...` | All |\n| Built-in mic | `ffmpeg -f avfoundation` / `pulse` / `alsa` | macOS, Linux |\n| Speaker (TTS) | `espeak-ng` / macOS `say` | macOS, Linux |\n| Smart home | Plugin system (Home Assistant, exec scripts) | All |\n\n---\n\n## Development\n\n```bash\n# Build\ngo build -o trioclaw ./cmd/trioclaw\n\n# Test\ngo test ./...\n\n# Run smoke tests\ngo test ./e2e/ -v\n\n# Cross-compile\nmake cross\n```\n\n---\n\n## Roadmap\n\n| Phase | What | Status |\n|-------|------|--------|\n| **MVP** | Camera capture, Gateway integration, `camera.snap`, `vision.analyze`, standalone CLI | Done |\n| **Phase 2** | YAML config, camera management, continuous monitoring (vision.watch SSE), notifications, HTTP API, clip recording, daily digest, trio-core auto-setup, plugin system | Done |\n| **Phase 3** | Product polish (see below) | In Progress |\n| **Phase 4** | STT via Whisper, TTS via espeak/`say`, audio monitoring | Planned |\n| **Phase 5** | GitHub releases, Docker image, OpenClaw Skill Hub listing | Planned |\n\n### Phase 3: Product Polish\n\n- [ ] **Web Dashboard** — Real-time alert timeline, camera status cards, stats, clip playback. Embedded in the Go binary via `embed.FS`, zero frontend build tools.\n- [ ] **Demo mode** (`trioclaw demo`) — Built-in sample video simulates a camera, produces events/alerts so users can experience the full flow in 30 seconds without any hardware.\n- [ ] **Interactive init** (`trioclaw init`) — Guided wizard that walks through trio-core setup, adding cameras, configuring notifications, and writes `config.yaml`.\n- [ ] **Rich notifications** — Telegram/Slack alerts with attached snapshot image, formatted message (camera name, time, condition, answer).\n- [ ] **README hero image** — Dashboard screenshot or terminal GIF showing the product in action.\n\n---\n\n## Related Projects\n\n| Project | Description |\n|---------|-------------|\n| [OpenClaw](https://github.com/openclaw/openclaw) | Personal AI assistant — the Gateway that TrioClaw connects to |\n| [ClawGo](https://github.com/openclaw/clawgo) | Go node for voice (ears + mouth) |\n| [MimiClaw](https://github.com/memovai/mimiclaw) | $5 chip AI assistant — standalone OpenClaw node |\n| [Trio API](https://trio.machinefi.com) | Vision Language Model API that powers TrioClaw's eyes |\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nBuilt with [Trio](https://trio.machinefi.com) by [MachineFi](https://github.com/machinefi).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmachinefi%2Ftrioclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmachinefi%2Ftrioclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmachinefi%2Ftrioclaw/lists"}