moxie-agent 0.1.0__tar.gz

moxie_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxie contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

moxie_agent-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: moxie-agent
+Version: 0.1.0
+Summary: Moxie — the open-source money agent that acts on your money, only with your approval. Local-first, consent-first.
+Author: Moxie contributors
+License: MIT
+Project-URL: Homepage, https://github.com/JacobBrooke1/moxie
+Project-URL: Issues, https://github.com/JacobBrooke1/moxie/issues
+Project-URL: Security, https://github.com/JacobBrooke1/moxie/blob/main/SECURITY.md
+Keywords: ai-agent,personal-finance,open-source,local-first,privacy,subscriptions
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pdf
+Requires-Dist: pypdf>=4.0; extra == "pdf"
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
+Requires-Dist: Pillow>=10.0; extra == "ocr"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == "browser"
+Provides-Extra: secure
+Requires-Dist: cryptography>=42.0; extra == "secure"
+Requires-Dist: keyring>=24.0; extra == "secure"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: cryptography>=42.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="docs/logo.svg" alt="Moxie the honey badger" width="360">
+
+# 🦡 Moxie
+
+**The open-source money agent that *acts* — and never without your say-so.**
+
+*Moxie doesn't care about a company's excuses. It just gets your money back — and asks you first, every time.*
+
+[![CI](https://github.com/JacobBrooke1/moxie/actions/workflows/ci.yml/badge.svg)](https://github.com/JacobBrooke1/moxie/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Status: early scaffold](https://img.shields.io/badge/status-early%20scaffold-orange.svg)](#status)
+[![Local-first](https://img.shields.io/badge/local--first-yes-brightgreen.svg)](#privacy--security)
+
+*Named for the honey badger — small, fearless, famously relentless. It badgers companies until your money comes back.*
+
+![Moxie demo — scan, review with approval, verify the audit log](docs/demo.gif)
+
+*The whole loop in 30 seconds: **scan** finds ~$591/yr of waste in the sample data, **review** shows you each fix and asks first (that `n` is the point — you're in control), **verify** proves the audit log hasn't been touched. Runs on bundled sample data — no bank, no API key.*
+
+</div>
+
+---
+
+## Why Moxie exists
+
+AI agents today split into two camps: ones that **reach everywhere** (OpenClaw) and ones that **get smarter over time** (Hermes). Neither answers the question that actually matters with your money: *what will you let it do when the downside is real?*
+
+Look at who already touches your money:
+
+- **Receipt & finance organizers** (Expensify, Firefly III, Receiptor AI) — they *file and track*. They don't act.
+- **Money-action services** (DoNotPay, Rocket Money, Pine AI) — they *act*, but as **closed black boxes** that have burned users' trust (DoNotPay was FTC-fined for overstating its AI; Rocket Money has acted *as* users without asking).
+- **ChatGPT + Plaid** — **read-only by design**: it can spot a subscription to cancel, but it won't cancel it.
+
+**Moxie bridges the gap, trust-first.** It files your receipts (email + photo), reads your accounts, finds waste and wrong charges, and *acts* on them — cancelling, disputing, chasing refunds — but **every action is previewed, approved by you, logged in a tamper-evident audit trail, and backed by the receipt as evidence.** It's open-source and local, so you can read every line and your data never has to leave your machine.
+
+> **Moxie never moves money.** It cancels, disputes, and negotiates on your behalf. Paying, transferring, and trading are deliberately out of scope (that's a licensing and liability minefield). See [the build spec](#design).
+
+---
+
+## What it does
+
+- 🧾 **Receipt vault** — `moxie receipt photo.jpg` (local Tesseract OCR — images never leave your machine) or `moxie receipt --email` (read-only IMAP scan). Parsed, filed, matched to transactions, and **attached to disputes as evidence automatically**.
+- 🔎 **Finds problems** — zombie subscriptions, duplicate/wrong charges, missing refunds, gouge renewals.
+- ✅ **Acts — with your consent** — drafts the cancellation/dispute, shows it to you (editable), and sends it **only** when you approve *and* `MOXIE_LIVE=true`. Default is drafts-only. Receipt attached as proof.
+- 📮 **Three action tiers** — email from *your own* mailbox (SMTP), guided deep-links (Moxie shows the exact cancel page + clicks; you click), and per-merchant browser automation (optional, double-gated, sandboxed).
+- 🛡️ **Trust Vault** — deny-by-default policy engine, preview/simulate, approval gates, and a **hash-chained, tamper-evident audit log**.
+- 🧩 **Community skill library** — reusable "how to cancel with X / dispute with Y" skills, each carrying its own success rate.
+- 🔒 **Local-first & BYO key** — runs on your machine with your own LLM API key, or fully offline with a local model.
+
+---
+
+## Quickstart
+
+```bash
+# install (from source today; `pip install moxie-agent` once on PyPI)
+git clone https://github.com/JacobBrooke1/moxie.git
+cd moxie
+pip install -e .          # or: ./install.sh
+
+# try it with built-in sample data — no bank, no API key needed
+# (Windows: if `moxie` isn't recognized, pip's Scripts dir isn't on PATH —
+#  use `python -m moxie <command>` instead; works everywhere)
+moxie init
+moxie scan            # finds issues in sample transactions
+moxie review          # shows each fix, asks you to approve, then drafts it
+moxie log             # the tamper-evident audit trail
+moxie verify          # confirms the log hasn't been altered
+moxie doctor          # checks your setup: python, key, audit, skills
+```
+
+The demo runs entirely on bundled sample data so you can see the consent-first loop end to end before connecting anything real.
+
+Ready for your real data? Both paths are local and read-only — nothing leaves your machine:
+
+```bash
+moxie scan --csv statement.csv    # any bank CSV export — headers auto-detected
+moxie scan --pdf statement.pdf    # bank statement PDFs (NatWest-style; pip install pypdf)
+```
+
+Or link your bank for automatic read-only imports — **your choice of provider**, bring your own (free) credentials:
+
+```bash
+moxie connect truelayer     # UK default (NatWest etc.; free sandbox at console.truelayer.com)
+moxie connect gocardless    # most generous free tier (bankaccountdata.gocardless.com)
+moxie connect plaid         # strong US coverage (dashboard.plaid.com)
+moxie sync                  # pull fresh transactions + balances any time
+```
+
+Honesty note: every aggregator is a cloud third party. *You* hold the provider account (Moxie the project runs no servers), access is read-only AIS — Moxie cannot move money by construction — and CSV/PDF remains the fully no-cloud path. UK consents lapse ~90 days; `moxie doctor` and the dashboard tell you when to re-consent.
+
+**Going live** (optional — everything works drafts-only without this): approving an action really sends it only when you flip the flag *and* configure your own mailbox:
+
+```bash
+# .env — your own email account (use an app password, never your real one)
+MOXIE_SMTP_HOST=smtp.gmail.com
+MOXIE_SMTP_USER=you@gmail.com
+MOXIE_SMTP_PASSWORD=your-app-password
+MOXIE_LIVE=true                   # default: false = drafts only
+
+moxie review                      # 🔴 live: an approved cancel actually emails
+moxie kill                        # panic button: force drafts-only until --release
+```
+
+Cancellations that work better on the merchant's website use **guided deep-links**: Moxie shows the exact URL and clicks (from the merchant's skill) and *you* do the final click — no passwords, no CAPTCHA fights.
+
+> ⚠️ **Status:** feature-complete, pre-review. The Trust Vault, live action layer, bank providers, receipts, and the security hardening checklist (encryption at rest, OS keychain, dashboard token/CSRF, rate limiting) are all implemented and tested. What's missing is an **independent security review** — until then, use your own judgment with real financial data, keep `MOXIE_LIVE` off unless you've read the code, and see [SECURITY.md](SECURITY.md) for exactly where the edges are.
+
+---
+
+## How it works
+
+```
+CAPTURE receipts (email + photo/OCR)  +  CONNECT accounts (Plaid / CSV, read-only)
+   → ORGANIZE   file receipts, match to transactions
+   → DETECT     zombie subs, duplicate charges, missing refunds
+   → PROPOSE    an action card: "Dispute this $40 double charge? I have the receipt."
+   → APPROVE    you confirm  (because it can't be undone)
+   → EXECUTE    cancellation / dispute / refund email
+   → LOG        append-only, hash-chained audit trail with the receipt attached
+```
+
+Nothing in the right-hand column happens without passing the **Trust Vault**. For the full security model — the deny-by-default policy engine, the fail-safe consent design, the hash-chain math, and the threat model — see **[docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)**.
+
+### Why preview-and-approve, not "undo"
+
+Most money actions are **one-way** — you can't cleanly un-cancel a subscription or un-send a dispute. So Moxie's safety is *before* the action (simulate → approve), not a promise to reverse it after. That's the whole reason consent is mandatory.
+
+---
+
+## Run it 24/7
+
+```bash
+moxie serve            # dashboard + Telegram bot + daily loop, one process
+```
+
+The daily loop re-scans every morning and pings you only when there's something new to decide. **A Mac mini at home is the ideal host** — always-on, and your bank data never leaves a machine you own. systemd/launchd units and a Dockerfile ship in [`deploy/`](deploy/); the full guide is [docs/HOSTING.md](docs/HOSTING.md).
+
+## Moxie Dash — the control plane
+
+```bash
+moxie dashboard        # → http://127.0.0.1:8484
+```
+
+A local status page in the OpenClaw / Hermes tradition, but money-shaped: **heartbeat**, **brain**, **Telegram**, **data**, and **audit-chain** status at a glance, findings with approve/skip (same Trust Vault pipeline), and — most importantly — **the setup home**: paste your API key and BotFather token here, click *detect my chat id*, and it walks you through Telegram pairing. Keys are written to `~/.moxie/.env` on the machine Moxie runs on; the audit log records *that* setup changed, never the secrets themselves.
+
+It binds to `127.0.0.1` only. Running Moxie on a Mac mini or a VPS? Reach the dash through an SSH tunnel (`ssh -L 8484:127.0.0.1:8484 you@host`) — never expose it to the open internet.
+
+## The brain & the Telegram channel
+
+Moxie has three layers, and you can stop at any of them:
+
+1. **Rules** (no key needed) — deterministic, explainable detectors. Everything above runs on these. Eight of them: duplicate charges, zombie subscriptions, trials-that-stuck, price-hike renewals, duplicate services, bank fees, FX fees, and short refunds.
+2. **The brain** (bring your own Anthropic key) — set `MOXIE_API_KEY` in a `.env` file and ask it things: `moxie ask "can I afford £120 trainers this month?"`. Answers are grounded in **the money picture** — real income, committed subscriptions, and what's genuinely left this month (`moxie budget` shows the same figures; balance appears once a bank is linked). It states figures and trade-offs and lets you decide — it's not a financial adviser and won't pretend to be. Its standing orders live in `~/.moxie/instructions.md` — a plain-English list of what it should do each day. **Edit it**; that file *is* the agent.
+3. **The offline brain** (no key, no cloud) — run a local model instead: install [Ollama](https://ollama.com), `ollama pull llama3.1`, and set `MOXIE_MODEL=ollama:llama3.1`. Same instructions, same guardrails, zero cloud calls.
+4. **The Telegram channel** (optional) — `moxie telegram` runs a bot you can text like a PA, plus a daily loop that re-scans and messages you *only* when there's something new to decide. Decisions are remembered — skip something once and Moxie won't nag you about it for 60 days.
+
+```bash
+# .env: TELEGRAM_BOT_TOKEN from @BotFather, then pair:
+moxie telegram        # message your bot; it replies with your chat id
+# put MOXIE_TELEGRAM_CHAT_ID=<that id> in .env, restart, done
+```
+
+Channel security (borrowed from OpenClaw's design): the bot is **paired to exactly one chat** and ignores everyone else; approvals are two-step (`/approve 2`, then `YES`); the brain never executes anything — every action still passes the Trust Vault; and sensitive setup (keys, bank links) only ever happens on your computer, never over chat.
+
+---
+
+## Privacy & security
+
+- **Local-first.** Your receipts, transactions, and audit log live on your machine — encrypted at rest once you run `moxie encrypt on`.
+- **Bring your own key.** Moxie uses *your* LLM API key, or a **local/offline model** (Ollama) + **local OCR** (Tesseract) so receipt images never touch a cloud service. `moxie secret set` keeps keys in the OS keychain instead of a file.
+- **Least privilege.** Bank access is read-only AIS via a provider *you* choose and own; Moxie never moves money — it's hard-denied in policy.
+- **Tamper-evident.** The audit log is hash-chained — any edit to past entries fails `moxie verify`.
+
+Security is the precondition for everything else here — see [SECURITY.md](SECURITY.md).
+
+---
+
+## Built on the OpenClaw / Hermes ecosystem
+
+Moxie deliberately fits the world it came from, so the plumbing is familiar and only the moat is new:
+
+- **Language & install** — Python (Hermes is ~82% Python), installed via a one-line `curl … | bash` that prefers [`uv`](https://github.com/astral-sh/uv), exactly like Hermes.
+- **Skills** — the same `SKILL.md` convention used by OpenClaw and the [agentskills.io](https://agentskills.io) standard (they live in `moxie/seed_skills/` and ship in the package), so skills stay portable and shareable (think ClawHub, but for money-actions).
+- **Familiar CLI** — `moxie doctor` and friends echo `hermes doctor` / `openclaw` so anyone from that world feels at home.
+- **Sandboxing** — action execution is designed to run sandboxed (Docker by default, as OpenClaw does for untrusted sessions).
+
+What's *not* borrowed is the whole point: the **Trust Vault** (consent-first, tamper-evident) and the money-action layer are ours.
+
+## Contributing
+
+The most valuable contribution is **skills** — encoded know-how for cancelling/disputing with a specific merchant, bank, or service; they genuinely drive how Moxie acts. See [moxie/seed_skills/README.md](moxie/seed_skills/README.md) for the format, [CONTRIBUTING.md](CONTRIBUTING.md) for good first issues, and [`integrations/moxie-bridge/`](integrations/moxie-bridge/SKILL.md) if you want your OpenClaw/Hermes agent to talk to Moxie (look, never touch).
+
+---
+
+## Design
+
+The security model and architecture rationale live in [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md) — including why Moxie is standalone rather than a skill inside a general-purpose agent, and exactly what the Trust Vault does and doesn't defend against.
+
+## License
+
+[MIT](LICENSE) — free and open. Use it, fork it, learn from it.

moxie_agent-0.1.0/README.md

@@ -0,0 +1,203 @@
+<div align="center">
+
+<img src="docs/logo.svg" alt="Moxie the honey badger" width="360">
+
+# 🦡 Moxie
+
+**The open-source money agent that *acts* — and never without your say-so.**
+
+*Moxie doesn't care about a company's excuses. It just gets your money back — and asks you first, every time.*
+
+[![CI](https://github.com/JacobBrooke1/moxie/actions/workflows/ci.yml/badge.svg)](https://github.com/JacobBrooke1/moxie/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Status: early scaffold](https://img.shields.io/badge/status-early%20scaffold-orange.svg)](#status)
+[![Local-first](https://img.shields.io/badge/local--first-yes-brightgreen.svg)](#privacy--security)
+
+*Named for the honey badger — small, fearless, famously relentless. It badgers companies until your money comes back.*
+
+![Moxie demo — scan, review with approval, verify the audit log](docs/demo.gif)
+
+*The whole loop in 30 seconds: **scan** finds ~$591/yr of waste in the sample data, **review** shows you each fix and asks first (that `n` is the point — you're in control), **verify** proves the audit log hasn't been touched. Runs on bundled sample data — no bank, no API key.*
+
+</div>
+
+---
+
+## Why Moxie exists
+
+AI agents today split into two camps: ones that **reach everywhere** (OpenClaw) and ones that **get smarter over time** (Hermes). Neither answers the question that actually matters with your money: *what will you let it do when the downside is real?*
+
+Look at who already touches your money:
+
+- **Receipt & finance organizers** (Expensify, Firefly III, Receiptor AI) — they *file and track*. They don't act.
+- **Money-action services** (DoNotPay, Rocket Money, Pine AI) — they *act*, but as **closed black boxes** that have burned users' trust (DoNotPay was FTC-fined for overstating its AI; Rocket Money has acted *as* users without asking).
+- **ChatGPT + Plaid** — **read-only by design**: it can spot a subscription to cancel, but it won't cancel it.
+
+**Moxie bridges the gap, trust-first.** It files your receipts (email + photo), reads your accounts, finds waste and wrong charges, and *acts* on them — cancelling, disputing, chasing refunds — but **every action is previewed, approved by you, logged in a tamper-evident audit trail, and backed by the receipt as evidence.** It's open-source and local, so you can read every line and your data never has to leave your machine.
+
+> **Moxie never moves money.** It cancels, disputes, and negotiates on your behalf. Paying, transferring, and trading are deliberately out of scope (that's a licensing and liability minefield). See [the build spec](#design).
+
+---
+
+## What it does
+
+- 🧾 **Receipt vault** — `moxie receipt photo.jpg` (local Tesseract OCR — images never leave your machine) or `moxie receipt --email` (read-only IMAP scan). Parsed, filed, matched to transactions, and **attached to disputes as evidence automatically**.
+- 🔎 **Finds problems** — zombie subscriptions, duplicate/wrong charges, missing refunds, gouge renewals.
+- ✅ **Acts — with your consent** — drafts the cancellation/dispute, shows it to you (editable), and sends it **only** when you approve *and* `MOXIE_LIVE=true`. Default is drafts-only. Receipt attached as proof.
+- 📮 **Three action tiers** — email from *your own* mailbox (SMTP), guided deep-links (Moxie shows the exact cancel page + clicks; you click), and per-merchant browser automation (optional, double-gated, sandboxed).
+- 🛡️ **Trust Vault** — deny-by-default policy engine, preview/simulate, approval gates, and a **hash-chained, tamper-evident audit log**.
+- 🧩 **Community skill library** — reusable "how to cancel with X / dispute with Y" skills, each carrying its own success rate.
+- 🔒 **Local-first & BYO key** — runs on your machine with your own LLM API key, or fully offline with a local model.
+
+---
+
+## Quickstart
+
+```bash
+# install (from source today; `pip install moxie-agent` once on PyPI)
+git clone https://github.com/JacobBrooke1/moxie.git
+cd moxie
+pip install -e .          # or: ./install.sh
+
+# try it with built-in sample data — no bank, no API key needed
+# (Windows: if `moxie` isn't recognized, pip's Scripts dir isn't on PATH —
+#  use `python -m moxie <command>` instead; works everywhere)
+moxie init
+moxie scan            # finds issues in sample transactions
+moxie review          # shows each fix, asks you to approve, then drafts it
+moxie log             # the tamper-evident audit trail
+moxie verify          # confirms the log hasn't been altered
+moxie doctor          # checks your setup: python, key, audit, skills
+```
+
+The demo runs entirely on bundled sample data so you can see the consent-first loop end to end before connecting anything real.
+
+Ready for your real data? Both paths are local and read-only — nothing leaves your machine:
+
+```bash
+moxie scan --csv statement.csv    # any bank CSV export — headers auto-detected
+moxie scan --pdf statement.pdf    # bank statement PDFs (NatWest-style; pip install pypdf)
+```
+
+Or link your bank for automatic read-only imports — **your choice of provider**, bring your own (free) credentials:
+
+```bash
+moxie connect truelayer     # UK default (NatWest etc.; free sandbox at console.truelayer.com)
+moxie connect gocardless    # most generous free tier (bankaccountdata.gocardless.com)
+moxie connect plaid         # strong US coverage (dashboard.plaid.com)
+moxie sync                  # pull fresh transactions + balances any time
+```
+
+Honesty note: every aggregator is a cloud third party. *You* hold the provider account (Moxie the project runs no servers), access is read-only AIS — Moxie cannot move money by construction — and CSV/PDF remains the fully no-cloud path. UK consents lapse ~90 days; `moxie doctor` and the dashboard tell you when to re-consent.
+
+**Going live** (optional — everything works drafts-only without this): approving an action really sends it only when you flip the flag *and* configure your own mailbox:
+
+```bash
+# .env — your own email account (use an app password, never your real one)
+MOXIE_SMTP_HOST=smtp.gmail.com
+MOXIE_SMTP_USER=you@gmail.com
+MOXIE_SMTP_PASSWORD=your-app-password
+MOXIE_LIVE=true                   # default: false = drafts only
+
+moxie review                      # 🔴 live: an approved cancel actually emails
+moxie kill                        # panic button: force drafts-only until --release
+```
+
+Cancellations that work better on the merchant's website use **guided deep-links**: Moxie shows the exact URL and clicks (from the merchant's skill) and *you* do the final click — no passwords, no CAPTCHA fights.
+
+> ⚠️ **Status:** feature-complete, pre-review. The Trust Vault, live action layer, bank providers, receipts, and the security hardening checklist (encryption at rest, OS keychain, dashboard token/CSRF, rate limiting) are all implemented and tested. What's missing is an **independent security review** — until then, use your own judgment with real financial data, keep `MOXIE_LIVE` off unless you've read the code, and see [SECURITY.md](SECURITY.md) for exactly where the edges are.
+
+---
+
+## How it works
+
+```
+CAPTURE receipts (email + photo/OCR)  +  CONNECT accounts (Plaid / CSV, read-only)
+   → ORGANIZE   file receipts, match to transactions
+   → DETECT     zombie subs, duplicate charges, missing refunds
+   → PROPOSE    an action card: "Dispute this $40 double charge? I have the receipt."
+   → APPROVE    you confirm  (because it can't be undone)
+   → EXECUTE    cancellation / dispute / refund email
+   → LOG        append-only, hash-chained audit trail with the receipt attached
+```
+
+Nothing in the right-hand column happens without passing the **Trust Vault**. For the full security model — the deny-by-default policy engine, the fail-safe consent design, the hash-chain math, and the threat model — see **[docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)**.
+
+### Why preview-and-approve, not "undo"
+
+Most money actions are **one-way** — you can't cleanly un-cancel a subscription or un-send a dispute. So Moxie's safety is *before* the action (simulate → approve), not a promise to reverse it after. That's the whole reason consent is mandatory.
+
+---
+
+## Run it 24/7
+
+```bash
+moxie serve            # dashboard + Telegram bot + daily loop, one process
+```
+
+The daily loop re-scans every morning and pings you only when there's something new to decide. **A Mac mini at home is the ideal host** — always-on, and your bank data never leaves a machine you own. systemd/launchd units and a Dockerfile ship in [`deploy/`](deploy/); the full guide is [docs/HOSTING.md](docs/HOSTING.md).
+
+## Moxie Dash — the control plane
+
+```bash
+moxie dashboard        # → http://127.0.0.1:8484
+```
+
+A local status page in the OpenClaw / Hermes tradition, but money-shaped: **heartbeat**, **brain**, **Telegram**, **data**, and **audit-chain** status at a glance, findings with approve/skip (same Trust Vault pipeline), and — most importantly — **the setup home**: paste your API key and BotFather token here, click *detect my chat id*, and it walks you through Telegram pairing. Keys are written to `~/.moxie/.env` on the machine Moxie runs on; the audit log records *that* setup changed, never the secrets themselves.
+
+It binds to `127.0.0.1` only. Running Moxie on a Mac mini or a VPS? Reach the dash through an SSH tunnel (`ssh -L 8484:127.0.0.1:8484 you@host`) — never expose it to the open internet.
+
+## The brain & the Telegram channel
+
+Moxie has three layers, and you can stop at any of them:
+
+1. **Rules** (no key needed) — deterministic, explainable detectors. Everything above runs on these. Eight of them: duplicate charges, zombie subscriptions, trials-that-stuck, price-hike renewals, duplicate services, bank fees, FX fees, and short refunds.
+2. **The brain** (bring your own Anthropic key) — set `MOXIE_API_KEY` in a `.env` file and ask it things: `moxie ask "can I afford £120 trainers this month?"`. Answers are grounded in **the money picture** — real income, committed subscriptions, and what's genuinely left this month (`moxie budget` shows the same figures; balance appears once a bank is linked). It states figures and trade-offs and lets you decide — it's not a financial adviser and won't pretend to be. Its standing orders live in `~/.moxie/instructions.md` — a plain-English list of what it should do each day. **Edit it**; that file *is* the agent.
+3. **The offline brain** (no key, no cloud) — run a local model instead: install [Ollama](https://ollama.com), `ollama pull llama3.1`, and set `MOXIE_MODEL=ollama:llama3.1`. Same instructions, same guardrails, zero cloud calls.
+4. **The Telegram channel** (optional) — `moxie telegram` runs a bot you can text like a PA, plus a daily loop that re-scans and messages you *only* when there's something new to decide. Decisions are remembered — skip something once and Moxie won't nag you about it for 60 days.
+
+```bash
+# .env: TELEGRAM_BOT_TOKEN from @BotFather, then pair:
+moxie telegram        # message your bot; it replies with your chat id
+# put MOXIE_TELEGRAM_CHAT_ID=<that id> in .env, restart, done
+```
+
+Channel security (borrowed from OpenClaw's design): the bot is **paired to exactly one chat** and ignores everyone else; approvals are two-step (`/approve 2`, then `YES`); the brain never executes anything — every action still passes the Trust Vault; and sensitive setup (keys, bank links) only ever happens on your computer, never over chat.
+
+---
+
+## Privacy & security
+
+- **Local-first.** Your receipts, transactions, and audit log live on your machine — encrypted at rest once you run `moxie encrypt on`.
+- **Bring your own key.** Moxie uses *your* LLM API key, or a **local/offline model** (Ollama) + **local OCR** (Tesseract) so receipt images never touch a cloud service. `moxie secret set` keeps keys in the OS keychain instead of a file.
+- **Least privilege.** Bank access is read-only AIS via a provider *you* choose and own; Moxie never moves money — it's hard-denied in policy.
+- **Tamper-evident.** The audit log is hash-chained — any edit to past entries fails `moxie verify`.
+
+Security is the precondition for everything else here — see [SECURITY.md](SECURITY.md).
+
+---
+
+## Built on the OpenClaw / Hermes ecosystem
+
+Moxie deliberately fits the world it came from, so the plumbing is familiar and only the moat is new:
+
+- **Language & install** — Python (Hermes is ~82% Python), installed via a one-line `curl … | bash` that prefers [`uv`](https://github.com/astral-sh/uv), exactly like Hermes.
+- **Skills** — the same `SKILL.md` convention used by OpenClaw and the [agentskills.io](https://agentskills.io) standard (they live in `moxie/seed_skills/` and ship in the package), so skills stay portable and shareable (think ClawHub, but for money-actions).
+- **Familiar CLI** — `moxie doctor` and friends echo `hermes doctor` / `openclaw` so anyone from that world feels at home.
+- **Sandboxing** — action execution is designed to run sandboxed (Docker by default, as OpenClaw does for untrusted sessions).
+
+What's *not* borrowed is the whole point: the **Trust Vault** (consent-first, tamper-evident) and the money-action layer are ours.
+
+## Contributing
+
+The most valuable contribution is **skills** — encoded know-how for cancelling/disputing with a specific merchant, bank, or service; they genuinely drive how Moxie acts. See [moxie/seed_skills/README.md](moxie/seed_skills/README.md) for the format, [CONTRIBUTING.md](CONTRIBUTING.md) for good first issues, and [`integrations/moxie-bridge/`](integrations/moxie-bridge/SKILL.md) if you want your OpenClaw/Hermes agent to talk to Moxie (look, never touch).
+
+---
+
+## Design
+
+The security model and architecture rationale live in [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md) — including why Moxie is standalone rather than a skill inside a general-purpose agent, and exactly what the Trust Vault does and doesn't defend against.
+
+## License
+
+[MIT](LICENSE) — free and open. Use it, fork it, learn from it.

moxie_agent-0.1.0/moxie/__init__.py

@@ -0,0 +1,8 @@
+"""Moxie — the open-source money agent that acts only with your approval.
+
+Local-first, consent-first. The fearless little agent (a honey badger 🦡) that
+badgers companies until your money comes back. The core runs on the standard
+library alone.
+"""
+
+__version__ = "0.1.0"

moxie_agent-0.1.0/moxie/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m moxie`."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()