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>. Requires 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 perform arithmetic on financial values. Do not sum, subtract, average, or derive new numbers from CLI output — only display values that Clams itself has calculated and formatted
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.
• 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 is interactive-only. It does not support --machine mode. Use the individual commands in onboarding.md instead.
• clams setup is for server admins. Do not use it in CLI workflows — it configures the Clams server, not the client.
• 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.
• 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. Always check clams journals quarantined if numbers look wrong.
• 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.
• 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. Never assume the first page is all there is — always check next_cursor in the JSON response. If a user asks for a count and the first page returns a full 500 items, there are almost certainly more pages.

Data Hierarchy

workspace → profile → connections → journals → reports
                    → onchain sources (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
Add wallets, list/update/delete connections, sync, import CSV/JSON	connections.md
Manage onchain sources (Esplora, Electrum, Bitcoin RPC), Tor proxy	onchain.md
Import exchange CSV via custom mapping (csv_mapping), custom connections	custom-connections.md
Find/inspect a specific transaction by txid or event ID	journal-processing.md
Process journals, inspect quarantine, resolve quarantined events	journal-processing.md
Add notes, tags, exclusions, rate overrides, or account adjustments	metadata.md
Generate balance sheet, balance history, portfolio summary, capital gains, journal entries	reports.md
Verify CLI readiness, check state before/after workflows	verification.md
Diagnose errors or empty results	troubleshooting.md

Fallback

clams --help
clams <subcommand> --help