Track spending, set period-based limits, and let ɳClaw surface AI-driven savings insights — all in plain conversation. Tell ɳClaw "I spent $18 on lunch today" and the expense is logged automatically.
claw-budget requires nself-ai for insights. nself-notify is optional for over-budget alerts.
nself license set nself_pro_xxxxx
nself plugin install ai claw-budget
nself build && nself startclaw-budget gives ɳClaw a full personal finance layer. Expenses are logged with amount, category, description, and date. Each category can carry a monthly spending limit. You can also declare recurring charges — subscriptions, rent, bills — so the plugin automatically accounts for them in your monthly totals.
The /budget/status endpoint returns spent-vs-limit for any period (week, month, year). /budget/summary groups spending by category or date range. /budget/insights calls the ai plugin to analyze patterns and return concrete savings suggestions.
Every endpoint is exposed to ɳClaw as a typed tool via /budget/internal/tools and /budget/ai/instructions, so you can manage your finances in natural language without touching an API.
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL | Yes | — | PostgreSQL connection string (set by nself automatically) |
PORT | No | 3725 | Plugin listen port |
PLUGIN_AI_INTERNAL_URL | No | http://plugin-ai:3709 | Internal URL of nself-ai (required for insights) |
| Method | Path | Description |
|---|---|---|
| GET | /health | Liveness probe |
| POST | /expenses | Log an expense (amount, category, description, date) |
| GET | /expenses | Search expenses (query, from, to, category_id) |
| GET | /expenses/:id | Get one expense |
| DELETE | /expenses/:id | Delete an expense |
| GET | /categories | List spending categories |
| POST | /categories | Create or upsert a category |
| DELETE | /categories/:id | Delete a category |
| POST | /limits | Set a budget limit (period: week | month | year) |
| GET | /limits | List all limits |
| DELETE | /limits/:id | Delete a limit |
| GET | /status | Spent vs limit for a period (period=week|month|year) |
| GET | /summary | Spending grouped by category or date range |
| GET | /insights | AI-driven savings insights for the period |
| GET | /recurring | List recurring charges |
| POST | /recurring | Add a recurring charge (subscriptions, bills) |
| DELETE | /recurring/:id | Remove a recurring charge |
| GET | /config | Current plugin configuration |
| PUT | /config | Update plugin configuration |
| GET | /config/schema | JSON Schema for config validation |
| Table | Purpose |
|---|---|
np_claw_budget_categories | Spending categories with optional monthly limit per category |
np_claw_budget_entries | Individual expense entries (amount, category, date, description) |
np_claw_budget_limits | Period-based spending limits (week / month / year) |
np_claw_budget_recurring | Recurring charges — subscriptions, rent, bills |
np_claw_budget_goals | Savings goals with target amount and deadline |
np_claw_budget_config | Per-user plugin configuration (currency, fiscal period start) |
All tables use user_id for per-user isolation.
ɳClaw registers these tools from claw-budget and invokes them automatically:
| Tool | What it does |
|---|---|
log_expense | Log an expense from a natural-language description |
get_budget_status | Return spent vs limit for the current week / month / year |
set_budget_limit | Create or update a period-based spending limit |
get_spending_summary | Spending breakdown grouped by category or date |
get_insights | AI-powered savings suggestions for the current period |
search_expenses | Full-text and date-range search over past expenses |
Once installed, claw-budget registers its tools with the claw plugin at startup. No extra configuration is needed. Ask ɳClaw anything budget-related in plain language:
You: I spent $45 on groceries today
ɳClaw: Logged — $45 in Groceries. You're at $312 of your $500 monthly food budget.
You: How am I doing this month?
ɳClaw: You've spent $1,240 of your $2,000 monthly budget with 11 days left.
Food: $312/500 · Transport: $180/300 · Entertainment: $90/150.
You: Where can I cut back?
ɳClaw: Your streaming subscriptions total $74/mo across 6 services.
Cancelling the two you haven't used in 60 days would save $22/mo.| Feature | claw-budget | YNAB / Monarch |
|---|---|---|
| Data ownership | Your Postgres instance | Vendor servers |
| Log via conversation | Yes — via ɳClaw | Manual entry or bank sync |
| AI insights | Yes — via nself-ai | Limited / subscription tier |
| Cost | $0.99/mo (ɳClaw bundle) | $14–$15/mo |
| Bank sync | Manual or via mux rules | Automatic (Plaid) |
| Issue | Fix |
|---|---|
| Insights always empty | Verify PLUGIN_AI_INTERNAL_URL is reachable from the claw-budget container |
/health returns 503 | Check that DATABASE_URL is set and Postgres is running |
| ɳClaw doesn't see budget tools | Restart the claw plugin after installing claw-budget so it re-fetches the tool manifest |
nself plugin remove claw-budgetPort: 3725 | Bundle: ɳClaw ($0.99/mo) or ɳSelf+ ($3.99/mo) | Requires: nself-ai | Last Updated: May 2026 | Plugin Version 1.1.1