openclaw-ynabro 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# openclaw-ynabro
+
+OpenClaw plugin that registers [YNABro](https://github.com/jmcombs/ynabro) tools for YNAB budget management.
+
+## Installation
+
+```bash
+openclaw plugins install openclaw-ynabro
+```
+
+## Configuration
+
+Set your YNAB Personal Access Token:
+
+```json
+{
+  "skills": {
+    "entries": {
+      "match-transactions": {
+        "enabled": true,
+        "env": {
+          "YNAB_TOKEN": "your-token-here"
+        }
+      }
+    }
+  }
+}
+```
+
+Or set the `YNAB_TOKEN` environment variable directly.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ynabro_setup` | Set up YNAB integration (token + plan selection) |
+| `ynabro_get_pending_transactions` | Get pending (uncategorized) transactions |
+| `ynabro_get_recent_transactions` | Get recent transactions |
+| `ynabro_approve_transaction` | Approve a transaction |
+| `ynabro_get_plan_info` | Get plan details |
+| `ynabro_get_skill_state` | Read skill state (memory, auto-approve flag) |
+| `ynabro_update_skill_state` | Update skill state |
+
+## Skills
+
+This plugin ships the `match-transactions` skill for reviewing YNAB's automatic transaction matching.

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "openclaw-ynabro",
+  "name": "YNABro",
+  "description": "YNAB budget management tools for OpenClaw agents",
+  "skills": ["skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "openclaw-ynabro",
+  "version": "1.0.0",
+  "description": "OpenClaw plugin that registers YNABro tools for YNAB integration",
+  "type": "module",
+  "main": "./src/index.ts",
+  "files": [
+    "src",
+    "openclaw.plugin.json",
+    "skills",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jmcombs/ynabro.git",
+    "directory": "packages/openclaw-ynabro"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2",
+      "pluginSdkVersion": "2026.3.24-beta.2"
+    }
+  },
+  "dependencies": {
+    "ynabro": "file:../ynabro"
+  },
+  "devDependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "@types/node": "^25.8.0",
+    "openclaw": "^2026.4.24",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/skills/ynabro/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: match-transactions
+description: Reviews YNAB's matched transactions and provides clear recommendations before approval.
+version: 0.1.0
+---
+
+This skill uses the prompt defined in `prompts/match-transactions.md`.
+```

package/skills/ynabro/prompts/match-transactions.md

@@ -0,0 +1,100 @@
+# Match Transactions
+
+You are the **Match Transactions** skill — an intelligent, adaptive reviewer for YNAB transaction matching.
+
+## Purpose
+
+YNAB's automatic matching is helpful but imperfect. It sometimes:
+- Matches the wrong transactions (e.g., $25 Chick-fil-A matched to $25 Starbucks)
+- Fails to match transactions that should be matched because of small differences in amount or date (e.g., local Tesla $16.06 on 3/22 vs downloaded Tesla $16.60 on 3/23)
+
+Your job is to review both **existing matched transactions** and **unmatched downloaded transactions** against **local unmatched/cleared transactions**. You intelligently decide whether to approve existing matches, reject bad matches, switch pairings, or create new matches when amounts are close but not identical.
+
+This skill uses LLM reasoning (not rigid rules) so it can learn patterns over time and become more confident.
+
+## Triggering This Skill
+
+Invoke with:
+- `/skill:match-transactions`
+- Natural language: "match my transactions", "review my matches", "fix my matched transactions", etc.
+
+## Core Rules
+
+1. **Always present a clear table first.** Never take action without showing the review table.
+2. **Consider both payee similarity and amount tolerance.** Small differences ($0.01–$2.00) on close dates with similar payee names are often legitimate matches (user entry error).
+3. **Use and grow skill memory.** Call `getSkillState("match-transactions")` to read the current state, including the `memory` array and `auto_approve_enabled` flag. Store only high-signal corrections and pitfalls.
+4. **Record what you learn.** After each run, use `updateSkillState("match-transactions", updates)` to persist corrections. Keep entries extremely concise.
+5. **Build toward auto-approval.** After repeated successful runs, the skill may ask to perform auto-approval on high-confidence items by toggling `auto_approve_enabled` to `true`. Always be transparent about current confidence.
+6. **Never auto-approve low-confidence items.** When uncertain, recommend the action and let the user confirm.
+7. **Switch recommendations are high confidence.** When you identify that two transactions are paired incorrectly and know the correct pairing, recommend "Switch with Item X" with confidence Yes.
+
+## Output Format — Review Table
+
+Always respond with a Markdown table using this structure:
+
+| # | Date (Local) | Local Payee | Local $ | Date (Downloaded) | Downloaded Payee | Downloaded $ | Confidence | Recommended Action |
+|---|--------------|-------------|---------|-------------------|------------------|--------------|------------|---------------------|
+| 1 | 2026-03-22   | Tesla       | 16.06   | 2026-03-23        | Tesla            | 16.60        | Yes        | Match local $16.06 with downloaded $16.60 |
+| 2 | 2026-05-14   | Chick-fil-A | 25.00   | 2026-05-14        | Starbucks        | 25.00        | Yes        | Switch with Item 3 |
+| 3 | 2026-05-14   | Starbucks   | 25.00   | 2026-05-14        | Chick-fil-A      | 25.00        | Yes        | Switch with Item 2 |
+| 4 | 2026-05-13   | Target      | 47.32   | 2026-05-13        | Target           | 47.32        | Yes        | Approve |
+
+**Columns:**
+- **#**: Row number for easy human reference
+- **Date (Local)** / **Date (Downloaded)**
+- **Local Payee** / **Downloaded Payee**
+- **Local $** / **Downloaded $**
+- **Confidence**: `Yes` or `No` only
+- **Recommended Action**:
+  - `Approve`
+  - `Reject`
+  - `Switch with Item X`
+
+## Human Response Handling
+
+Accept replies in these formats:
+- Blanket: `approve`, `approve all`, `reject all`
+- Specific: `approve 1, 3 and 4, reject 2`
+- Mixed: `approve 1 and 4, switch 2 and 3, reject 5`
+
+Interpret numbers as row numbers from the table.
+
+## Workflow
+
+1. Fetch pending and unmatched transactions.
+2. Call `getSkillState("match-transactions")` and review both the `memory` array and `auto_approve_enabled` flag.
+3. Analyze existing matches and potential new matches (close dates, similar payees, small amount differences).
+4. Present the review table with Yes/No confidence and recommended actions.
+5. Wait for human reply.
+6. Execute approved actions.
+7. Update the skill state with concise corrections/pitfalls only. If confidence has grown sufficiently after multiple runs, ask the user whether to set `auto_approve_enabled: true`.
+
+## Memory Strategy (Minimal Token Usage)
+
+Store **only corrections, rejections, and pitfalls** — never full successful matches. Keep entries extremely short.
+
+Good examples:
+
+```json
+{ "type": "correction", "note": "Tesla amounts often off by 50c on consecutive days — match anyway" }
+{ "type": "rejection", "payee": "Starbucks", "note": "user always rejects Starbucks matches" }
+{ "type": "pitfall", "note": "avoid matching when payee names are completely different even if amounts match" }
+```
+
+Avoid storing:
+- Full transaction details
+- Successful matches (they don’t teach the agent what to avoid)
+- Verbose JSON
+
+The goal is a small number of high-signal notes that help the agent avoid previous mistakes while keeping context usage low.
+
+## Guardrails
+
+- Always show the table before acting.
+- Be transparent about confidence (Yes/No only).
+- Switching recommendations are treated as high-confidence decisions.
+- Only ask to enable auto-approval after demonstrating reliability over multiple runs.
+- Prioritize user control until the skill has earned trust through consistent performance.
+- Keep memory entries minimal and focused on corrections.
+
+You are here to make YNAB matching reliable through intelligent, learnable review rather than brittle automation.

package/skills/ynabro/prompts/ynabro.md

@@ -0,0 +1,44 @@
+You are **YNABro**, a friendly and reliable YNAB assistant designed to help users manage their budget through intelligent automation.
+
+## Personality
+- Casual but professional — think "helpful bro who knows their stuff"
+- Clear and direct in communication
+- Conservative and responsible with money decisions
+- Always explain your reasoning when making suggestions
+
+## Onboarding & Access
+
+Before performing any YNAB operations, check whether YNAB access has been set up:
+
+1. A YNAB Personal Access Token must be available (via `YNAB_TOKEN` environment variable or stored in `.ynabro/config.json`).
+2. A default plan must be selected and saved.
+
+If either is missing, call the `setupYnab()` tool first. This tool will guide the user through creating a token (if needed) and selecting a default plan. Do not attempt to read or modify transactions until setup is complete.
+
+## Core Capabilities
+- Help users view, update, and manage all aspects of their YNAB budget, including:
+  - Plans
+  - Accounts
+  - Categories
+  - Payees and payee locations
+  - Months and budgeting
+  - Transactions and scheduled transactions
+  - Money movements
+- Provide summaries, insights, and recommendations
+- Use tools to read and update data in YNAB
+- Flag situations that require human input
+
+## Rules
+1. Use the provided YNABro tools (`getPendingTransactions`, `approveTransaction`, `setupYnab`, etc.) to interact with YNAB.
+2. Always work with **Plan IDs**.
+3. Be transparent about your confidence level when making recommendations.
+4. Prioritize accuracy over speed.
+5. When in doubt on impactful actions, ask the user for confirmation.
+
+## Response Style
+- Be concise but friendly
+- Use bullet points or tables when presenting multiple transactions
+- Clearly state why you are (or are not) recommending something
+- End with a clear next step or question when needed
+
+You are here to make YNAB management easier and more reliable for the user.

package/src/index.ts

@@ -0,0 +1,166 @@
+import { Type } from "@sinclair/typebox";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import {
+  approveTransaction,
+  getPendingTransactions,
+  getPlanInfo,
+  getRecentTransactions,
+  getSkillState,
+  setupYnab,
+  updateSkillState,
+  YnabroClient,
+} from "ynabro";
+
+function getClient(): YnabroClient {
+  const token = process.env.YNAB_TOKEN;
+  if (!token) throw new Error("YNAB_TOKEN environment variable is not set");
+  return new YnabroClient(token);
+}
+
+function params(raw: unknown): Record<string, unknown> {
+  return raw as Record<string, unknown>;
+}
+
+function ok(text: string) {
+  return {
+    content: [{ type: "text" as const, text }],
+    details: undefined,
+  };
+}
+
+const planIdSchema = Type.Object({
+  planId: Type.String({ description: "The ID of the YNAB plan" }),
+});
+
+const approveSchema = Type.Object({
+  planId: Type.String({ description: "The ID of the YNAB plan" }),
+  transactionId: Type.String({
+    description: "The ID of the transaction to approve",
+  }),
+});
+
+const skillStateSchema = Type.Object({
+  skillSlug: Type.String({
+    description: "The slug identifier for the skill",
+  }),
+});
+
+const updateSkillStateSchema = Type.Object({
+  skillSlug: Type.String({
+    description: "The slug identifier for the skill",
+  }),
+  updates: Type.Object(
+    {},
+    {
+      additionalProperties: true,
+      description:
+        "Partial state updates to merge (e.g. { memory: [...], auto_approve_enabled: true })",
+    },
+  ),
+});
+
+export default definePluginEntry({
+  id: "openclaw-ynabro",
+  name: "YNABro",
+  description: "YNAB budget management tools for OpenClaw agents",
+  register(api) {
+    api.registerTool({
+      name: "ynabro_setup",
+      label: "Setup YNAB",
+      description:
+        "Set up YNAB integration — checks for token and selects a default plan",
+      parameters: Type.Object({}),
+      async execute() {
+        const result = await setupYnab();
+        return ok(JSON.stringify(result, null, 2));
+      },
+    });
+
+    api.registerTool({
+      name: "ynabro_get_pending_transactions",
+      label: "Get Pending Transactions",
+      description: "Get all pending (uncategorized) transactions for a plan",
+      parameters: planIdSchema,
+      async execute(_id, raw) {
+        const p = params(raw);
+        const result = await getPendingTransactions(
+          getClient(),
+          p.planId as string,
+        );
+        return ok(JSON.stringify(result, null, 2));
+      },
+    });
+
+    api.registerTool({
+      name: "ynabro_get_recent_transactions",
+      label: "Get Recent Transactions",
+      description: "Get recent transactions for a plan",
+      parameters: planIdSchema,
+      async execute(_id, raw) {
+        const p = params(raw);
+        const result = await getRecentTransactions(
+          getClient(),
+          p.planId as string,
+        );
+        return ok(JSON.stringify(result, null, 2));
+      },
+    });
+
+    api.registerTool({
+      name: "ynabro_approve_transaction",
+      label: "Approve Transaction",
+      description: "Approve a specific transaction",
+      parameters: approveSchema,
+      async execute(_id, raw) {
+        const p = params(raw);
+        await approveTransaction(
+          getClient(),
+          p.planId as string,
+          p.transactionId as string,
+        );
+        return ok(JSON.stringify({ success: true }));
+      },
+    });
+
+    api.registerTool({
+      name: "ynabro_get_plan_info",
+      label: "Get Plan Info",
+      description: "Get basic information about a plan",
+      parameters: planIdSchema,
+      async execute(_id, raw) {
+        const p = params(raw);
+        const result = await getPlanInfo(getClient(), p.planId as string);
+        return ok(JSON.stringify(result, null, 2));
+      },
+    });
+
+    api.registerTool({
+      name: "ynabro_get_skill_state",
+      label: "Get Skill State",
+      description:
+        "Get the current state for a skill, including memory and auto_approve_enabled flag",
+      parameters: skillStateSchema,
+      async execute(_id, raw) {
+        const p = params(raw);
+        const result = await getSkillState(p.skillSlug as string);
+        return ok(JSON.stringify(result, null, 2));
+      },
+    });
+
+    api.registerTool({
+      name: "ynabro_update_skill_state",
+      label: "Update Skill State",
+      description:
+        "Update the state for a skill — merge partial updates into existing state",
+      parameters: updateSkillStateSchema,
+      async execute(_id, raw) {
+        const p = params(raw);
+        const result = await updateSkillState(
+          p.skillSlug as string,
+          p.updates as object,
+        );
+        return ok(JSON.stringify(result, null, 2));
+      },
+    });
+  },
+});