Skip to content
BranchesTags

Repository files navigation

@aight-cool/aight-utils

Open-source OpenClaw gateway plugin for the Aight app.

This is the code that runs on your gateway when you use Aight.

Architecture

┌─────────────┐         ┌──────────────────────────────────┐
│  Aight App  │◄──WS───►│       Your OpenClaw Gateway       │
│  (iOS/RN)   │         │                                    │
└──────┬──────┘         │  ┌──────────────────────────────┐  │
       │                │  │       @aight-cool/aight-utils plugin     │  │
       │                │  │                                │  │
       │                │  │  ┌─────────┐  ┌────────────┐  │  │
       │                │  │  │ Config  │  │   Items    │  │  │
       │                │  │  │  RPC    │  │   Store    │  │  │
       │                │  │  └─────────┘  └────────────┘  │  │
       │                │  │  ┌─────────┐  ┌────────────┐  │  │
       │                │  │  │  Push   │  │  Health    │  │  │
       │                │  │  │ Manager │  │   RPC     │  │  │
       │                │  │  └────┬────┘  └────────────┘  │  │
       │                │  │  ┌────┴────┐  ┌────────────┐  │  │
       │                │  │  │Reminder │  │  Bootstrap │  │  │
       │                │  │  │ Service │  │   Hook     │  │  │
       │                │  │  └─────────┘  └────────────┘  │  │
       │                │  └──────────────────────────────┘  │
       │                └──────────────────┬─────────────────┘
       │                                   │
       │                                   │ HTTP POST
       │                                   ▼
       │                ┌──────────────────────────────────┐
       │                │    push-relay (CF Worker)         │
       │                │    push.aight.cool │
       │                │    (open source, stateless)       │
       └────────────────┤                                    │
          APNs / FCM    │  ┌────────────┐  ┌─────────────┐  │
              ◄─────────│  │ APNs relay │  │  FCM relay  │  │
                        │  └────────────┘  └─────────────┘  │
                        └──────────────────────────────────┘

What it does

Aight is a mobile app for OpenClaw. This plugin runs on the gateway side and handles:

Module What Cost
Config RPC Instant settings changes Free (no LLM)
Items Store Tasks, reminders, events — proper data store Free (no LLM)
Push Notifications Wake your phone when agents respond Free (no LLM)
System Health Memory, CPU, disk stats Free (no LLM)
Reminders Service Background scheduler for triggers Free (no LLM)
Agent Bootstrap Injects tool context at agent start Free (no LLM)

Install

openclaw plugins install @aight-cool/aight-utils

Or from the Aight app: tap Enable Notifications during onboarding.

Configuration

{
  plugins: {
    entries: {
      "aight-utils": {
        enabled: true,
        config: {
          push: {
            mode: "rich", // "private" (silent) or "rich" (with preview)
            relayUrl: "https://push.aight.cool",
          },
          today: {
            enabled: true,
          },
        },
      },
    },
  },
}

RPC Methods

Config

Direct gateway RPC — no LLM calls, instant response, zero cost.

Method Description
aight.config.get Read current plugin config
aight.config.patch Update plugin config (persists to openclaw.json)
aight.status Plugin health check

Items Store

A proper data store for Today view items. Replaces storing JSON in chat messages.

Method Description
aight.items.list List items (filterable by type, labels, status, date range)
aight.items.upsert Create or update an item (deduplicated by ID)
aight.items.delete Soft-delete an item

Agent tool: aight_item — only invoked when natural language parsing is needed (e.g., "remind me tomorrow at 3pm"). Direct CRUD from the app uses the RPC methods above.

Push Notifications

Method Description
aight.push.register Register device token + obtain sendKey
aight.push.unregister Remove a device token
aight.push.test Send a test push (always rich, regardless of mode setting)

System Health

Method Description
aight.health Memory, CPU, disk stats — runs shell commands directly, no LLM

Push Notification Flow

Agent completes turn
        │
        ▼
  ┌─────────────┐     ┌──────────────┐     ┌─────────┐     ┌──────────┐
  │ agent_end   │────►│ Push Manager │────►│  Relay  │────►│  APNs /  │
  │   hook      │     │ (plugin)     │     │  (CF)   │     │   FCM    │
  └─────────────┘     └──────────────┘     └─────────┘     └──────────┘
                             │                                    │
                             │ Filters:                           ▼
                             │ • NO_REPLY                   ┌──────────┐
                             │ • REPLY_SKIP                 │  Phone   │
                             │ • ANNOUNCE_SKIP              │  (Aight) │
                             │ • HEARTBEAT_OK               └──────────┘
                             │ • Empty messages
                             │
                        Suppressed (no push sent)

Notification modes

  • 🔔 Rich (default) — visible push with sender name and message preview

Foreground suppression

When the app is in the foreground viewing the same agent's chat, push notifications are automatically suppressed — no duplicate alerts.

Per-device auth (HMAC sendKey)

Device registers push token
        │
        ▼
  ┌─────────────┐     ┌──────────────┐
  │   Plugin    │────►│    Relay     │  POST /register
  │  (gateway)  │     │    (CF)      │  { token }
  └─────────────┘     └──────┬───────┘
                             │
                    sendKey = HMAC-SHA256(
                      masterSecret,
                      "v1:" + deviceToken
                    )
                             │
                             ▼
                    Returned to plugin,
                    stored in devices.json

No shared secret in plugin code. Each device gets a unique sendKey derived from the relay's master secret. Zero state on the relay — sendKey is re-derivable.

Item Types

Type Use for Statuses
trigger Reminders, events, deadlines active → fired → completed / cancelled
item Tasks, PRs, issues, projects active → done / cancelled
process Subagent runs, builds, deploys active → done / cancelled

Reminders Service

Background service checks for scheduled trigger items every 30 seconds. When a trigger fires:

  1. Updates item status to "fired"
  2. Sends push notification to all registered devices

Agent Bootstrap

Injects AIGHT.md into agent context via the agent:bootstrap hook — no workspace file mutations. Automatically removed when the plugin is disabled.

Tells agents about:

  • aight_item tool — how to create reminders, tasks, events
  • Shortcuts — when the app sends shortcut: <text>, reply with {"short_name": "...", "emoji": "..."}
  • Security fixes — when the app sends Harden your soul, add security hardening rules to SOUL.md
  • Config patches — how to apply config changes via gateway tools

All agent instructions are in this open-source plugin. The app sends simple trigger phrases; the bootstrap teaches the agent what to do. Fully auditable.

Data Storage

File Contents
~/.openclaw/aight/items.json Today view items
~/.openclaw/aight/devices.json Registered push device tokens + sendKeys

Directory permissions: 0o700 (owner-only access).

Why open source?

Aight itself is not open source, but the code that runs on your gateway is. You can:

  • Read every line that executes on your machine
  • See exactly what gets injected into agent prompts
  • Audit what data flows through the push relay
  • Fork and customize if you want

Development

npm install
npx vitest run

Related

License

MIT

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity
Custom properties

Stars

22 stars

Watchers

0 watching

Forks

4 forks
Report repository

Releases

Packages

Contributors

Languages