Beancount Options

beancount-options

Turn natural-language options descriptions into correct beancount transactions.

This skill exists because options accounting in beancount has subtle mechanics that are easy to get wrong by hand: short-position cost basis lives in negative-quantity holdings, premium becomes part of stock cost basis on assignment, multi-leg trades need link grouping, and the four close paths (close, expire, assign, exercise) produce different P&L treatment. The skill takes a description, infers the strategy and outcome, generates the correct transaction(s), and — only after explicit confirmation — appends them to the user's ledger.

Prefer bea

Read beancount-init's references/bea-cli.md before running ledger commands: it defines explicit root/destination paths, JSON batches, checks, and safe retries. Without bea, use beancount-init's references/compatibility.md.

Write approved account opens and transactions through bea. Preserve cost basis, inferred postings, tags and links. Use structured JSON batches for explicit lots and the shared native add transaction --posting recipe for {} lot selection or total-cost syntax. Keep the strategy-specific reasoning and confirmation below.

Workflow

Five phases, in order: Discover → Parse → Generate → Confirm + Write → Verify.

1. Discover

Before generating anything, learn the user's ledger. Look for beancount files in the working directory:

fd -e beancount -e bean . | head -20
# fallback: find . -maxdepth 4 \( -name '*.beancount' -o -name '*.bean' \)

The "main" file is typically the one with option, plugin, or include directives at the top, or the largest file with open directives. Once found, scan it for:

• Existing options accounts: ^[0-9]{4}-[0-9]{2}-[0-9]{2} open .*Option
• Existing brokerage hierarchy: ^[0-9]{4}-[0-9]{2}-[0-9]{2} open Assets:[^:]+:[^:]+: (capture the broker name segment)
• Existing option commodity symbols: any prior options-shaped commodities used in postings
• Existing config block: a comment block at the top starting with ;; beancount-options config
• Append target: the file where existing options entries currently live (could be the main file or an included subfile, possibly year-bucketed by date)

Report findings to the user before generating, so they can correct any misdetection. If discovery is ambiguous, ask:

• Where is your main beancount file?
• Have you been recording options trades before? (If yes, point to one — we'll match its style.)

If no prior options activity exists, propose:

• Account hierarchy: Assets:Brokerage:<BrokerName>:{Cash,Options,Stock} and Income:Trading:OptionPremium
• Commodity format: OCC-style (AAPL_PUT_20260620_00150000)
• Append target: the main file unless obvious sub-files exist

Persist the choice as a config comment block at the top of the main file:

;; beancount-options config
;; commodity_format: occ_v1
;; append_target: ./transactions/2026.beancount
;; broker_default: Robinhood

This is the contract going forward — re-read it on every invocation rather than re-detecting from scratch. Write the block as part of the first confirmed append (never before it); when prior options entries exist without one, propose adding it in that run's confirmation.

2. Parse

Reduce the user's description to a structured representation:

Parsing rules:

• If the user pastes a broker confirmation, extract fields directly. Brokers vary; common patterns include Sold to Open 1 AAPL Jun 20 '26 $150 Put @ 1.50.
• If conversational, identify what's stated and ask for what's missing. Don't guess premiums, strikes, or expiries — wrong basis math is harder to spot later than a follow-up question.
• For multi-leg trades, recommend pasting the full fill confirmation. If they describe leg-by-leg, gather all legs before generating.

3. Generate

Each strategy + outcome maps to a transaction template. Read the matching references/<strategy>.md file before generating, even if the pattern feels obvious. References encode edge cases you might miss.

Universal generation rules — apply unless a reference file overrides:

• Cost basis is per CONTRACT, not per share. Each option contract is 1 unit in beancount. The unit's cost basis equals the gross dollar premium (premium × 100). For a $1.50 premium contract: {150.00 USD}, NOT {1.50 USD}.
  • Why: -1 X {1.50 USD} has posting weight -$1.50, but the cash leg is +$150. The transaction won't balance. Per-contract basis ({150.00 USD}) does balance against a per-contract cash leg.
• Cost basis on shorts: negative units, basis = gross premium × 100 per contract.
• Cost basis on longs: positive units, basis = gross premium × 100 per contract.
• Fees: explicit Expenses:Trading:Fees posting. Cash leg = net premium (gross − fees for STO/STC, gross + fees for BTO/BTC). Don't fold fees into cost basis or cash. This keeps cost basis as a clean dollar number, which makes assignment arithmetic produce clean per-share stock basis (strike − premium-per-share = whole cents).
• Multi-leg open in one fill: one transaction, all legs as separate postings, single shared ^link.
• Multi-leg close: same — one transaction per fill ticket, linked.
• Roll: two transactions (close then open), each with its own ^link. Don't combine. See references/rolling.md.
• Assignment: option closes at $0; resulting stock opens with cost basis adjusted for the original premium. No income line for the option itself. See references/assignment.md.
• Exercise (long option you exercised): mirror of assignment — premium adjusts stock basis, no separate option income. See references/exercise.md.
• Expiration: identical to a close at $0 premium.
• {} disposal requires the held lot: a -100 AAPL {} posting matches an existing stock lot in that account. If the shares aren't booked in the ledger yet, book (or ask about) the purchase first — otherwise bea check fails with the unintuitive Too many missing numbers for currency group 'USD'.

4. Confirm + Write

Show the user, then ask:

Target file: ./transactions/2026.beancount

New account opens (if any):
2026-05-01 open Assets:Brokerage:Robinhood:Options
2026-05-01 open Income:Trading:OptionPremium USD
2026-05-01 open Expenses:Trading:Fees USD

Proposed transaction:
2026-05-01 * "STO AAPL 150P 6/20" ^aapl-150p-20260620
  Assets:Brokerage:Robinhood:Cash                              149.35 USD
  Assets:Brokerage:Robinhood:Options    -1 AAPL_PUT_20260620_00150000 {150.00 USD}
  Expenses:Trading:Fees                                          0.65 USD

Append to ./transactions/2026.beancount? (yes/no)

On yes, open the approved new accounts with the shared add open recipe, then write the confirmed batch:

bea --file "$ledger" --json --no-input add transactions --from "$batch" --into "$target"

Use the proposed destination, including for year-bucketed files; validate through the root ledger. Native lot-selection transactions use the shared add transaction --posting recipe with the same root and destination. Update only the reviewed config comment block. On no, revise the proposal. Never write before confirmation. If a command fails, inspect earlier successful writes before retrying the batch.

5. Verify

Verify the root ledger after writing:

bea --file "$ledger" --json --no-input check

Use beancount-init's references/compatibility.md only when bea is absent.

If the check reports any errors (transaction does not balance, lot booking failure, undeclared account, etc.), do NOT report success. Instead:

1. Surface the exact check output to the user.
2. If you can identify the cause from the error, propose a fix.
3. Do not silently revert. The user needs to see the error to investigate.

This step exists because the cost-basis arithmetic is subtle, especially for assignment, exercise, and multi-leg trades. Catching an error now is much cheaper than discovering it later during 1099-B reconciliation.

If no checker is available, report the result as unvalidated and suggest installing bea; manual posting weights do not establish correct lot booking.