# QuidClaw

Zero-barrier personal CFO.

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

QuidClaw is an open-source [Claude Code Plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that turns Claude into your personal CFO using [Beancount](https://beancount.github.io/) 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 / 中文文档](README.zh-CN.md)

## 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](https://docs.astral.sh/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:

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

Or clone and run:

```bash
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).

<details>
<summary><b>Claude Desktop</b></summary>

Add to your `claude_desktop_config.json` ([Settings → Developer → Edit Config](https://modelcontextprotocol.io/quickstart/user)):

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

Restart Claude Desktop.

</details>

<details>
<summary><b>Claude Code (MCP only)</b></summary>

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

</details>

<details>
<summary><b>Codex</b></summary>

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

```bash
uv tool install --python 3.13 quidclaw
```

Add to `~/.codex/config.toml`:

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

</details>

<details>
<summary><b>Other MCP clients</b></summary>

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

```
uvx --python 3.13 quidclaw
```

</details>

### Install from source

For contributors or users who prefer not to use [uv](https://docs.astral.sh/uv/):

```bash
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:

```json
{
  "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](docs/mcp-tools.md) for full parameter details.

## Development

See [Install from source](#install-from-source) above, then:

```bash
pytest
```

See [Architecture](docs/architecture.md) for design details.

## Author

**Yue Jiang** — [GitHub](https://github.com/thorb)

## License

This project is licensed under the [GNU General Public License v2.0](LICENSE), the same license used by [Beancount](https://github.com/beancount/beancount).
