quidclaw 0.2.0

Zero-barrier personal CFO — Claude Code Plugin powered by Beancount

QuidClaw

Zero-barrier personal CFO.

Local-first. Privacy by design. Your data never leaves your machine.

QuidClaw is an open-source Claude Code Plugin that turns Claude into your personal CFO using Beancount double-entry accounting. No financial background needed — just talk naturally about your money and QuidClaw handles the bookkeeping.

"Lunch was $12, paid with Apple Pay" → proper double-entry transaction recorded in your local ledger.

Chinese / 中文文档

Why QuidClaw

• Privacy first — All data stored locally as plain text. No servers, no cloud, no telemetry. Nothing ever leaves your machine.
• You own your data — Standard Beancount .bean files you can read, edit, and version control. No vendor lock-in, no proprietary formats.
• Zero barrier — No financial knowledge required. Talk naturally, and QuidClaw translates into proper accounting.

How It Works

                         ┌─────────────────────────────┐
You ──→ Claude Code ──→  │  QuidClaw Plugin             │
                         │  ┌─────────┐  ┌───────────┐ │
                         │  │ Skills  │  │  Agents   │ │  ──→  your project folder
                         │  │ Hooks   │  │  MCP Tools│ │       (local data)
                         │  └─────────┘  └───────────┘ │
                         └─────────────────────────────┘

• Skills — AI workflows for onboarding, bill import, reconciliation, reports, anomaly detection
• Agents — Specialized subprocesses for bill parsing and document organization
• Hooks — Automatic triggers (e.g., check inbox when you start a session)
• MCP Tools — 16 data operations for reading and writing your ledger

QuidClaw doesn't run any AI model. It's a bridge between Claude and the Beancount accounting engine.

Features

• Record transactions via natural language
• Multi-currency support (USD, EUR, CNY, etc.)
• Import bills — drop PDFs, CSVs, or screenshots into your inbox and QuidClaw parses them
• Smart deduplication — detects and prevents duplicate entries during import
• Document organization — files are automatically archived by date
• Financial knowledge base — stores insurance policies, subscriptions, asset details as structured notes
• Anomaly detection — flags duplicate charges, subscription price changes, unusual spending
• Balance queries and reconciliation
• Financial reports (income statement, balance sheet, spending trends)
• Flexible BQL (Beancount Query Language) queries
• Price tracking for stocks, crypto, and forex

Prerequisites

• uv — Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

Getting Started

Claude Code (recommended)

QuidClaw works best as a Claude Code Plugin, giving you the full experience — skills, agents, hooks, and MCP tools:

claude --plugin-dir /path/to/quidclaw

Or clone and run:

git clone https://github.com/thorb/quidclaw.git
claude --plugin-dir ./quidclaw

MCP-only setup

You can also use QuidClaw as a standalone MCP server with any MCP-compatible client. This gives you the 16 MCP tools without the Plugin extras (skills, agents, hooks).

Claude Desktop

Add to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "quidclaw": {
      "command": "uvx",
      "args": ["--python", "3.13", "quidclaw"]
    }
  }
}

Restart Claude Desktop.

Claude Code (MCP only)

claude mcp add quidclaw -- uvx --python 3.13 quidclaw

Codex

Codex runs MCP servers in a sandbox, so uvx won't work directly. Install first, then configure:

uv tool install --python 3.13 quidclaw

Add to ~/.codex/config.toml:

[mcp_servers.quidclaw]
command = "quidclaw"
args = []
type = "stdio"

Other MCP clients

QuidClaw is a standard MCP server using stdio transport. Configure your client to run:

uvx --python 3.13 quidclaw

Install from source

For contributors or users who prefer not to use uv:

git clone https://github.com/thorb/quidclaw.git
cd quidclaw
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Then use the full Python path in your client config:

{
  "command": "/absolute/path/to/quidclaw/.venv/bin/python",
  "args": ["-m", "quidclaw"]
}

Replace the path with the output of which python (run inside the activated venv).

Usage

Once connected, just talk naturally:

You: Help me get started

AI: Welcome! Which language do you prefer? / 欢迎！你希望用哪种语言？

You: 中文

AI: 你好！我是你的私人财务助理。怎么称呼你？

You: 叫我小明就好

AI: 小明，你管理的是个人财务还是公司的？

...

AI: 好的，我已经了解了你的大致情况。现在最重要的是把你的银行流水导入进来——把文件放到 inbox 文件夹，我来处理。

Data Storage

QuidClaw uses a directory-as-project model — there is no global default directory. You create a folder for your finances (e.g., ~/my-finances/), open Claude Code there, and QuidClaw auto-detects it as the project root. All data is stored locally as plain text:

~/my-finances/
├── ledger/                # Beancount ledger
│   ├── main.bean          #   includes all other files
│   ├── accounts.bean      #   account definitions
│   ├── prices.bean        #   price directives
│   └── 2026/
│       ├── 2026-01.bean   #   January transactions
│       └── ...
├── inbox/                 # Drop zone — put files here for import
├── documents/             # Organized archive (auto-managed)
│   └── 2026/01/           #   Filed by year and month
├── notes/                 # Financial knowledge base
│   ├── profile.md         #   User profile
│   ├── calendar.md        #   Financial calendar
│   ├── assets/            #   Property, vehicles, investments
│   ├── liabilities/       #   Loans, mortgages
│   ├── insurance/         #   Policy details
│   ├── accounts/          #   Bank and brokerage accounts
│   ├── subscriptions/     #   Recurring charges
│   ├── income/            #   Salary, side income
│   ├── decisions/         #   Financial decisions log
│   └── journal/           #   Free-form financial notes
└── reports/               # Generated reports

Plugin Components

Skills (7)

Skill	Triggers when...
onboarding	New user, no existing ledger
import-bills	Files dropped in inbox, user uploads documents
reconcile	Before any financial analysis — ensures data accuracy
monthly-review	User asks for spending summary or monthly report
detect-anomalies	User asks about suspicious charges or subscription review
organize-documents	New files in inbox need archiving
financial-memory	User mentions financial facts worth remembering

Agents (2)

Agent	Purpose
bill-parser	Parse PDFs, CSVs, and images into transactions
document-organizer	Classify and archive files

Hooks (1)

Hook	Trigger	Action
inbox-check	Session start	Silently checks inbox for unprocessed files

MCP Tools

QuidClaw exposes 16 tools to AI clients:

Tool	Description
set_data_dir	Set the data directory path
init_ledger	Initialize ledger with default or custom accounts
add_account	Open a new account
close_account	Close an account
list_accounts	List accounts, optionally filtered by type
add_transaction	Record a transaction
get_balance	Query account balances
balance_check	Verify balance for reconciliation
query	Execute arbitrary BQL queries
report	Generate income statement or balance sheet
fetch_prices	Fetch commodity prices
	Reports & Analysis
monthly_summary	Income, expenses, savings for a month
spending_by_category	Ranked category breakdown
month_comparison	Month-over-month comparison
largest_transactions	Top N biggest transactions
detect_anomalies	Find duplicates, subscriptions, outliers

See MCP Tools Reference for full parameter details.

Development

See Install from source above, then:

pytest

See Architecture for design details.

Author

Yue Jiang — GitHub

License

This project is licensed under the GNU General Public License v2.0, the same license used by Beancount.