# Clams

> Use this skill when the user wants to do bookkeeping, accounting, or tax reporting for Bitcoin and Lightning. This includes tracking cost basis, generating capital gains reports, viewing balances, and managing journal entries. Applies even if they don't mention "Clams" directly — any request about BTC profit/loss, tax reports, portfolio value, cost basis tracking, or bitcoin accounting should use this skill.

- Skill: `clams-tech/clams` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add clams-tech/clams`
- Raw SKILL.md: https://api.skillmd.com/api/skills/clams-tech/clams/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- Author: clams-tech (https://skillmd.com/u/clams-tech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/clams-tech/clams

---


## Skill Directory

All `scripts/` paths in this skill are relative to the directory containing this SKILL.md file. Before running any script, resolve the absolute path to this skill's directory first. For example, if this file is at `~/.claude/skills/clams/SKILL.md`, then scripts are at `~/.claude/skills/clams/scripts/`.

## Rules

1. **Before running your first `clams` command in a session**, source the user's shell profile to ensure PATH is set: `source ~/.zshenv 2>/dev/null; source ~/.bashrc 2>/dev/null`. Only needed once per session.
2. **Always read the relevant reference file before running a command.** Do not guess flags or syntax — check the reference first
3. **Use `--machine --format json`** for commands whose output you need to parse or pipe to a script
4. **Use `--format plain`** when the user wants to see report output in the terminal — display the CLI output directly, do not reformat it
5. **Processing order**: sync → `clams rates sync` → `clams journals process` → reports
6. **Default report formats**: use `--format plain` for display reports (balance sheet, balance history, portfolio summary) and `--format csv --output <path>` for data reports (capital gains, journal entries). **Only generate PDF when the user explicitly asks for it.**
7. **For PDF reports** (only when requested): pipe JSON through `<skill-dir>/scripts/render-<report>.sh --pdf <path>`. PDF needs WeasyPrint. **If the render script exits with code 3 (`WeasyPrint is required ...`):** do NOT run an unprompted install. Generate the report as `--format plain` or `--format csv` instead, tell the user PDF needs WeasyPrint, and offer the documented one-time install (`brew install weasyprint` on macOS; distro package on Linux) — run it only with their confirmation, then retry. If WeasyPrint is installed somewhere unusual, set `CLAMS_WEASYPRINT=/full/path/to/weasyprint`.
8. **Never** summarize or reformat amounts from CLI output — use render scripts, `--format plain`, or `--format csv` to let the CLI format them
9. **Never compute or derive financial values; presentation formatting of a single value is allowed.** Do not sum, subtract, average, ratio, infer signs from account type, or otherwise produce a *new* figure from CLI output. You **may** render a single engine field human-readable: a fixed-constant unit scale (sats÷100,000,000, cents÷100), decimal/locale formatting, a currency symbol, a `%`, or a readable date. Combining or deriving across fields is computation and belongs in the engine — display only what Clams calculated.
10. **There is no `clams reports export` command** — PDF and CSV are produced as described above
11. **On errors**: read the error JSON (`code` and `message` fields) before diagnosing — do not guess the cause. If the error isn't clear, retry the command with `--debug` for more detailed output

## Gotchas

- **Empty reports?** You forgot `clams journals process`. This must run after every sync/import and before any report. It's the #1 mistake.
- **Amounts are in millisatoshis.** Never convert, round, summarize, or display raw JSON amounts. Always pipe through the render scripts or use `--format csv`. (BTC and Liquid L-BTC follow this; Liquid issued assets such as USDt use their own scale — but you never need it, because you only render the engine's formatted output. See [liquid.md](references/liquid.md).)
- **`clams reports export` does not exist.** For PDF, pipe JSON through `<skill-dir>/scripts/render-*.sh`. For CSV, use `--format csv --output <path>` on the report command.
- **`clams init` guides login, license payment, and workspace/profile creation.** It does not support `--machine` mode, but runs non-interactively with `--no-input --new-workspace-label <L> --new-profile-label <L>` (plus `--payment` when a license checkout is needed). For step-by-step control use the individual commands in [onboarding.md](references/onboarding.md).
- **`clams setup` is client onboarding, not server administration.** It initializes the backend data root, OAuth credentials, and license (server administration lives under `clams server`). It is safe in CLI workflows — but it can start a license checkout, so see the payment rules in [licensing.md](references/licensing.md) before running it.
- **Paid workflows are license- and capacity-gated.** Reports, syncs, and profile/workspace creation need an active license; profile creation also needs free profile capacity on the instance. On `Profile capacity limit reached` or license/authorization errors, check `clams license status` and `clams instance capacity status` — see [licensing.md](references/licensing.md). **Never initiate a checkout, renewal, or capacity purchase without an explicit user request, and never accept checkout terms on the user's behalf.**
- **On-chain wallets need an onchain source first.** `XPub`, `Descriptor`, and `Address` connections will fail to sync without one. Create it during onboarding (step 7). When creating these connections, auto-resolve the onchain source and network — see "Resolving Onchain Source and Network" in [connections.md](references/connections.md). Do not ask the user unless genuinely ambiguous. **Liquid** (`LiquidDescriptor`) needs its own Liquid-family source (`LiquidEsplora`/`LiquidElectrum`) — a Bitcoin source will not work; see [liquid.md](references/liquid.md).
- **Re-process after metadata changes.** Notes, tags, exclusions, rate overrides, and account adjustments don't take effect until you run `clams journals process` again.
- **Omitting `--excluded` removes the exclusion.** `clams metadata records excluded set --event-id <ID>` without the `--excluded` flag un-excludes the event — this is intentional but counterintuitive.
- **Quarantine blocks accurate reports.** Unresolved quarantined events are omitted from reports, so surface any quarantine to the user *before* producing reports. Always check `clams journals quarantined` if numbers look wrong. A quarantine that looks collaborative is often just incomplete onchain sync (an address gap beyond the connection's gap limit) — don't assume coinjoin/privacy activity; ask the root-cause questions and prefer a wider-gap re-sync when the cause is missing wallet history. See [journal-processing.md](references/journal-processing.md#quarantine-diagnose-root-cause).
- **All JSON responses are wrapped in a `data` envelope.** The shape is `{"kind": "...", "schema_version": 1, "data": ...}`. Always access `.data` to get the actual payload — lists may be at `.data` (array) or `.data.items` (paginated).
- **`--machine` requires `--format json`.** Never combine `--machine` with `--format csv` or `--format plain` — it will error. Use `--machine --format json` for scripting, or drop `--machine` and use `--format plain` / `--format csv` directly.
- **Not all reports support CSV.** Only capital gains and journal entries have CSV output. Balance sheet and portfolio summary support plain text and PDF only. See the format support table in [reports.md](references/reports.md).
- **PDF reports are summary documents, not line-item records.** The capital-gains and portfolio-summary PDFs contain summary figures only — no per-transaction tables. For a complete line-item record, use the **CSV** export (capital gains → Capital Gains CSV; portfolio → Journal Entries or Capital Gains CSV, since Portfolio Summary has no CSV of its own). Only generate a PDF when the user explicitly wants a presentable summary.
- **The render scripts are presentation-formatting templaters (rule 9 applied).** They format *individual* engine fields via `scripts/format.sh` — sats→BTC, cents→fiat, currency symbol + 2dp, `%`, readable dates — and nothing else. They do **not** compute totals, ratios, charts, or invert signs; multi-field derivations stay the engine's job. Balance-sheet connection rows are filtered to `included_kinds` so the PDF matches `clams reports balance-sheet` (row selection, not sign logic). Do not add computation to the skill to "fix" the output.
- **PDF is best-effort — never dead-end on WeasyPrint.** The render scripts resolve WeasyPrint robustly (PATH, Homebrew, pip-user, `python3 -m weasyprint`, `$CLAMS_WEASYPRINT`) and *functionally verify* it can render — so a Homebrew install that isn't on the agent's PATH still works, and a broken pip install is rejected automatically. If nothing works they exit **3** with install guidance. Treat that as "fall back to plain/CSV and offer the install", not as a failed request.
- **Rapid CLI calls trigger rate limiting.** Making many requests in quick succession (e.g., paginating through events) causes the backend to return empty responses. These look like auth errors but are transient. When paginating, add a 0.5 s delay between pages and retry on empty responses (up to 3 attempts with a 2 s backoff). See the pagination section in [journal-processing.md](references/journal-processing.md).
- **Event counts can be large.** Lightning connections can have tens of thousands of events. Use `clams journals events count` — it returns `unique_total` plus `by_event_kind` and `by_connection` breakdowns from the latest processed snapshot, so you don't paginate for per-connection/per-kind totals. Two gotchas: `count` has no filter flags (for a count filtered by tag/note/date/account, paginate `clams journals events list` instead), and it can error (`CLAMS_E_UNKNOWN`, "snapshot rows are not ordered") on profiles with Liquid peg-bridge events — fall back to pagination there. When paginating, never assume the first page is all there is: always check `next_cursor`.

## Data Hierarchy

```
workspace → profile → connections → journals → reports
                    → onchain sources (Bitcoin + Liquid families; for on-chain wallets)
                    → metadata (notes, tags, exclusions)
```

## Report Selection

| User is asking about... | Report |
|---|---|
| Cost basis, net worth, unrealized gains, portfolio value, average cost | Portfolio Summary |
| Realized gains/losses, tax reporting, disposals, capital gains | Capital Gains |
| Current balances by account/connection, assets vs liabilities | Balance Sheet |
| How balances changed over time, balance trends | Balance History |
| Raw transaction data, ledger export | Journal Entries |

## Workflow Routing

| User wants to... | Reference |
|---|---|
| Log in, create workspace/profile, configure settings, set up onchain source | [onboarding.md](references/onboarding.md) |
| Add wallets, list/update/delete connections, sync, import CSV/JSON | [connections.md](references/connections.md) |
| Manage onchain sources (Esplora, Electrum, Bitcoin RPC), Tor proxy | [onchain.md](references/onchain.md) |
| Work with Liquid wallets, L-BTC, or Liquid assets (USDt); Liquid onchain source | [liquid.md](references/liquid.md) |
| Import exchange CSV via custom mapping (csv_mapping), custom connections | [custom-connections.md](references/custom-connections.md) |
| Find/inspect a specific transaction by txid or event ID | [journal-processing.md](references/journal-processing.md) |
| Process journals, inspect quarantine, diagnose root cause, resolve quarantined events | [journal-processing.md](references/journal-processing.md) |
| Link two events as a self-transfer (manual transfer links) | [journal-processing.md](references/journal-processing.md) |
| Add notes, tags, exclusions, rate overrides, or account adjustments | [metadata.md](references/metadata.md) |
| List accounts, create/update/delete custom accounts (chart of accounts) | [accounts.md](references/accounts.md) |
| Generate balance sheet, balance history, portfolio summary, capital gains, journal entries | [reports.md](references/reports.md) |
| Check license status, renew, pay invoices, view/buy profile capacity, instance status/billing owner | [licensing.md](references/licensing.md) |
| Verify CLI readiness, check state before/after workflows | [verification.md](references/verification.md) |
| Diagnose errors or empty results | [troubleshooting.md](references/troubleshooting.md) |

## Fallback

```sh
clams --help
clams <subcommand> --help
```