{"id":45157554,"url":"https://github.com/betterclaw-app/betterclaw","last_synced_at":"2026-04-06T16:01:00.299Z","repository":{"id":339511461,"uuid":"1162234671","full_name":"BetterClaw-app/betterclaw","owner":"BetterClaw-app","description":"OpenClaw plugin: intelligent context layer for BetterClaw iOS companion app","archived":false,"fork":false,"pushed_at":"2026-04-06T12:10:01.000Z","size":3368,"stargazers_count":0,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T12:24:36.457Z","etag":null,"topics":["betterclaw","ios","openclaw","openclaw-plugin"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@betterclaw-app/betterclaw","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BetterClaw-app.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-02-20T02:36:44.000Z","updated_at":"2026-04-06T12:09:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/BetterClaw-app/betterclaw","commit_stats":null,"previous_names":["betterclaw-app/betterclaw","betterclaw-app/betterclaw-plugin"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/BetterClaw-app/betterclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetterClaw-app%2Fbetterclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetterClaw-app%2Fbetterclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetterClaw-app%2Fbetterclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetterClaw-app%2Fbetterclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BetterClaw-app","download_url":"https://codeload.github.com/BetterClaw-app/betterclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetterClaw-app%2Fbetterclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31479006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T14:34:32.243Z","status":"ssl_error","status_checked_at":"2026-04-06T14:34:31.723Z","response_time":112,"last_error":"SSL_read: 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":["betterclaw","ios","openclaw","openclaw-plugin"],"created_at":"2026-02-20T05:02:57.620Z","updated_at":"2026-04-06T16:01:00.294Z","avatar_url":"https://github.com/BetterClaw-app.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"banner.png\" alt=\"BetterClaw\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eOpenClaw plugin for the BetterClaw iOS app\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@betterclaw-app/betterclaw\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@betterclaw-app/betterclaw?style=flat-square\u0026color=blue\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/BetterClaw-app/betterclaw/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/BetterClaw-app/betterclaw?style=flat-square\" alt=\"license\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@betterclaw-app/betterclaw\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@betterclaw-app/betterclaw?style=flat-square\u0026color=green\" alt=\"downloads\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://openclaw.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-OpenClaw-orange?style=flat-square\" alt=\"OpenClaw\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is this?\n\nThis is the server-side plugin for [BetterClaw](https://betterclaw.app), an iOS app that connects your iPhone's sensors to your [OpenClaw](https://openclaw.dev) AI agent. The app streams device events (location, battery, health, geofences) to your gateway — this plugin decides what to do with them.\n\nThe plugin differentiates between **free** and **premium** tiers:\n\n- **Free** — passive context store. The agent can pull device snapshots via `get_context`, but no events are pushed proactively.\n- **Premium** — full smart mode pipeline with rules-based filtering, LLM triage, engagement tracking, and a daily learner that adapts to your preferences.\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003cimg src=\".github/architecture.svg\" alt=\"BetterClaw Plugin Architecture\" width=\"500\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n## Features\n\n- **Tier-Aware Routing** — `check_tier` tool tells the agent whether to use node commands (premium, fresh data) or `get_context` (free, cached snapshots). Includes a 24h cache TTL so the agent doesn't re-check every turn.\n- **Free = Pull-Only** — Events are stored for context but never triaged or pushed. `get_context` with staleness indicators (`dataAgeSeconds`) is the only data source.\n- **Premium Smart Mode** — Rules engine + LLM triage with fail-closed error handling and budget-aware prompts. Daily push budget prevents event spam.\n- **Engagement Tracking** — Deterministic transcript scanner finds pushed messages by timestamp, then an LLM classifies user engagement as `engaged`, `ignored`, or `unclear`. Feeds into the learner.\n- **Adaptive Learner** — Daily subagent builds a simplified triage profile (`summary` + `interruptionTolerance`) from event history, engagement data, and workspace memory.\n- **Calibration Period** — First 3 days after install, triage runs in rules-only mode while the system collects engagement data. Skipped automatically for users upgrading from v2.\n- **Device Context** — Rolling state snapshot with per-field timestamps and `dataAgeSeconds`: battery, GPS, zone occupancy, health metrics, activity classification.\n- **Pattern Recognition** — Daily analysis computes location routines, health trends (7d/30d baselines), and event frequency stats.\n- **Per-Device Config** — iOS app can override push budget at runtime via RPC.\n- **Agent Tools** — `check_tier` for routing decisions, `get_context` for patterns/trends/cached state.\n- **CLI Setup** — `openclaw betterclaw setup` configures gateway allowedCommands automatically.\n\n## Requirements\n\n- [BetterClaw iOS app](https://github.com/BetterClaw-app/BetterClaw-ios) installed and connected to your gateway\n- [OpenClaw](https://openclaw.dev) gateway (2025.12+)\n\n## Install\n\n```bash\nopenclaw plugins install @betterclaw-app/betterclaw\nopenclaw betterclaw setup   # configures gateway allowedCommands\n```\n\n## Configure\n\nAdd to your `openclaw.json`:\n\n```jsonc\n{\n  \"plugins\": {\n    \"entries\": {\n      \"betterclaw\": {\n        \"enabled\": true,\n        \"config\": {\n          \"triageModel\": \"openai/gpt-4o-mini\",\n          \"pushBudgetPerDay\": 10,\n          \"patternWindowDays\": 14,\n          \"analysisHour\": 5,\n          \"calibrationDays\": 3\n        }\n      }\n    }\n  }\n}\n```\n\nAll config keys are optional — defaults are shown above.\n\n### Config Reference\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `triageModel` | `openai/gpt-4o-mini` | Model for per-event triage and engagement classification |\n| `triageApiBase` | -- | Optional base URL for OpenAI-compatible endpoint (e.g., Ollama) |\n| `pushBudgetPerDay` | `10` | Max events forwarded to the agent per day |\n| `patternWindowDays` | `14` | Days of event history used for pattern computation |\n| `analysisHour` | `5` | Hour (0-23, system timezone) for daily pattern + learner analysis |\n| `calibrationDays` | `3` | Days of rules-only triage before learner profile kicks in |\n\n\u003e **Migration from v2:** `llmModel` still works as a deprecated alias for `triageModel`. `proactiveEnabled` is ignored (proactive triggers removed in v3).\n\n## How It Works\n\n### Event Pipeline\n\nEvery device event from the BetterClaw app goes through the plugin:\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003cimg src=\".github/pipeline.svg\" alt=\"Event Pipeline\" width=\"350\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n### Background Services\n\n- **Pattern Engine + Reaction Scanner + Learner** (daily at `analysisHour`) — Computes location routines, health trends, event stats. Then scans session transcripts for engagement with past pushes (deterministic timestamp search + LLM classification). Finally runs a subagent to build a personalized triage profile from engagement data and workspace memory.\n\n### Agent Tools\n\n| Tool | Purpose |\n|------|---------|\n| `check_tier` | Returns tier + routing instructions + cache TTL. No device data. Call first. |\n| `get_context` | Returns patterns, trends, zone state, cached device snapshots with `dataAgeSeconds`. |\n\n### Gateway RPCs\n\n| RPC | Direction | Purpose |\n|-----|-----------|---------|\n| `betterclaw.event` | iOS -\u003e plugin | Send a device event for processing |\n| `betterclaw.ping` | iOS -\u003e plugin | Heartbeat: sync tier + smartMode, init calibration |\n| `betterclaw.config` | iOS -\u003e plugin | Per-device settings override |\n| `betterclaw.context` | iOS -\u003e plugin | Full context for iOS Context tab (includes `calibrating` flag) |\n| `betterclaw.snapshot` | iOS -\u003e plugin | Bulk device state catch-up |\n| `betterclaw.learn` | iOS -\u003e plugin | Trigger on-demand triage profile learning |\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/bc` | Show current device context snapshot in chat |\n\n## Compatibility\n\n| Plugin | BetterClaw iOS | OpenClaw |\n|--------|----------------|----------|\n| 3.x    | 2.x+           | 2025.12+ |\n| 2.x    | 2.x+           | 2025.12+ |\n| 1.x    | 1.x            | 2025.12+ |\n\n## License\n\n[AGPL-3.0](LICENSE) -- Free to use, modify, and self-host. Derivative works must remain open source.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetterclaw-app%2Fbetterclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbetterclaw-app%2Fbetterclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetterclaw-app%2Fbetterclaw/lists"}