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.)
• 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.
• 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 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. 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. 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.
• 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.
• 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.
• 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.
• 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

Workflow Routing

Fallback

clams --help
clams <subcommand> --help