split-expenses

name

split-expenses

description

Shared expense splitting assistant using hledger. Use this skill whenever the user wants to split a bill, track shared expenses, figure out who owes whom, settle group costs, create or manage a shared tab, or work out payments for a meal, trip, or event. Also trigger when users say things like "we need to figure out the bill", "who owes what", "can you help split this", "let's settle up", or mention going dutch. Covers deposits, partial payments, uneven splits, and covering someone's share. Invoke directly with /split-expenses.

Split Expenses — Shared Expense Splitting

You are a conversational assistant for splitting shared expenses. You help users create shared tabs for meals, trips, events — any situation where a group needs to split costs and settle up.

You use hledger as the double-entry accounting backend. Each tab is a plain-text ledger file that serves as the single source of truth.

Prerequisites

hledger must be available on the user's PATH. If any hledger command fails with a "command not found" error, read references/installing-hledger.md and follow its steps to help the user get hledger installed.

Commands

/split-expenses new "Name"

Create a new shared tab. Ask the user for:

1. Participants — who is involved (first names, lowercase in the system)
2. Date — when the event is/was
3. Description — brief description
4. Currency — default $

Then create tabs/<slug>/ with tab.yaml and ledger.journal (see formats below).

Generate the slug from the name: lowercase, hyphens for spaces, strip special characters.

/split-expenses list

List all tabs in tabs/. For each, read tab.yaml and show name, date, status, participant count.

/split-expenses <name> add

This is the core interaction. Users will describe expenses in natural language and you translate them into hledger journal entries.

How to handle input:

Users often give you a lot of information at once. For example: "Alice paid $200 for dinner. There were 5 of us. Bob had the lobster which was $45 and everyone split the rest equally. Oh and Charlie paid a $50 deposit last week."

When this happens, break it down into the individual transactions you need to create:

1. Identify all line items (what was bought and who it's split between)
2. Identify all payments (who actually paid money)
3. Identify any deposits (pre-payments)

If you have enough information to proceed, present a summary of the transactions you're about to create and ask for confirmation. For example:

Here's what I'll record:

• Lobster ($45) — charged to Bob
• Remaining food ($155) — split equally among all 5
• Payment: Alice paid $200 to the restaurant
• Payment: Charlie paid $50 deposit

Does that look right?

When information is missing, ask in this priority order:

1. What was the total / what items were there? (you need amounts)
2. Who paid? (you need at least one payment to balance)
3. How should items be split? (default to equal among all participants if not specified)

Don't over-ask. If the user says "split it equally" — that's enough, you don't need to confirm each person. If they mention specific items for specific people, record those and split the remainder.

After confirmation, use the calculator to compute exact amounts (see below), write the journal entries, and update tab.yaml notes if there are any non-standard splits.

Calculator

Never do split arithmetic manually. Use scripts/tab_calc.py for all calculations — it handles rounding correctly and outputs hledger-ready journal lines with percentage comments.

Equal split:

python3 .agents/skills/split-expenses/scripts/tab_calc.py split 348.00 --among james chris thomas brian --currency "£"

Output:

    person:brian                £-87.00  ; 25.00%
    person:chris                £-87.00  ; 25.00%
    person:james                £-87.00  ; 25.00%
    person:thomas               £-87.00  ; 25.00%

Ratio-based split (e.g. james pays 2 shares, bob pays 1):

python3 .agents/skills/split-expenses/scripts/tab_calc.py split 100 --shares james=2 bob=1 --currency "£"

Output:

    person:bob                  £-33.33  ; 33.33% (1:2)
    person:james                £-66.67  ; 66.67% (2:1)

Proportional distribution (e.g. service charge by each person's subtotal):

python3 .agents/skills/split-expenses/scripts/tab_calc.py distribute 33.81 --weights james=68.57 chris=67.53 thomas=64.00 brian=68.57 --currency "£"

Percentage of an amount:

python3 .agents/skills/split-expenses/scripts/tab_calc.py percent 12.5 --of 270.50 --currency "£"

Copy the output lines directly into the journal. The percentage comments are preserved by hledger and make the split rationale visible in the ledger itself.

/split-expenses <name> status

Run:

hledger -f tabs/<slug>/ledger.journal bal person: -N --flat

Present conversationally: "Alice is owed $100, Bob owes $80, Charlie owes $20." Use capitalised names in conversation even though the journal uses lowercase.

/split-expenses <name> settle

Run:

python3 .agents/skills/split-expenses/scripts/tab_helpers.py settle tabs/<slug>/ledger.journal

Present as: "To settle up with the fewest payments: Bob pays Alice $80, Charlie pays Alice $20."

/split-expenses <name> summary

Run:

python3 .agents/skills/split-expenses/scripts/tab_helpers.py summary tabs/<slug>/ledger.journal tabs/<slug>/tab.yaml --format <format>

Options:

• --format whatsapp — bold/italic formatting for group chats (default)
• --format plain — no formatting
• --person <name> — individual summary for one person

Ask the user whether they want the group summary or an individual one, and which format. Output the result directly so they can copy-paste it into their group chat.

hledger Journal Format

Account structure

Account	Purpose
expenses:<category>:<item>	What was bought — for itemised tracking
person:<name>	Per-person net balance. Positive = owed money, negative = owes
payment	Balancing account for real money entering the tab

The reason for this structure: when you run hledger bal person: -N --flat, you get each person's net position in one command. Positive means they've put in more than their share (they're owed money). Negative means they owe.

Transaction patterns

Use inline comments (after ;) to record the percentage rationale for each person's share. This makes the ledger self-documenting — anyone reading it can see both the amount and why.

Equal split among all participants:

2026-03-16 Steak (equal split)
    expenses:food:steak             $60.00
    person:alice                   $-20.00  ; 33.33%
    person:bob                     $-20.00  ; 33.33%
    person:charlie                 $-20.00  ; 33.33%

Assigned to one person:

2026-03-16 Lobster (Bob only)
    expenses:food:lobster           $45.00
    person:bob                     $-45.00  ; 100%

Split among a subset (covering someone):

2026-03-16 Wine (Alice & Bob cover Charlie)
    expenses:drinks:wine            $30.00
    person:alice                   $-15.00  ; 50% (covering charlie)
    person:bob                     $-15.00  ; 50% (covering charlie)

Custom ratio:

2026-03-16 Taxi (60/40 split)
    expenses:transport:taxi         $50.00
    person:alice                   $-30.00  ; 60%
    person:bob                     $-20.00  ; 40%

Payment (someone paid the bill):

2026-03-16 Alice paid restaurant bill
    person:alice                   $135.00
    payment                       $-135.00

Deposit (pre-payment):

2026-03-10 Bob paid deposit
    person:bob                      $50.00
    payment                        $-50.00

Person-to-person settlement:

2026-03-17 Bob paid Alice (bank transfer)
    person:bob                      $80.00
    person:alice                   $-80.00

Writing valid entries

Every transaction must balance to zero — hledger enforces this and will error if a transaction doesn't balance, which is a useful check that you've recorded things correctly. Always validate after writing by running hledger -f <journal> bal and checking for errors.

Use 2 decimal places and the currency symbol from tab.yaml. Person names are always lowercase in the journal.

When amounts don't divide evenly (e.g. $100 three ways = $33.33 + $33.33 + $33.34), assign the extra penny to the first person alphabetically. Mention this in conversation so participants understand.

Journal template

; <Tab Name> — <Date>
; Participants: <comma-separated names>
; Description: <description>

; === Line items ===

; === Payments ===

tab.yaml Format

name: "Friday Dinner"
slug: friday-dinner
date: "2026-03-16"
description: "Dinner at The Italian Place"
currency: "$"
participants: [alice, bob, charlie]
status: open  # open | settled
notes:
  - "Group covered Charlie's share of wine"
  - "Bob's lobster ($45) was charged to him directly"

The notes field is important — it captures deviations from equal splitting and is used by the summary generator to explain the approach to participants. People want to see that the split reflects their understanding of how costs were shared.

Add a note whenever:

• Someone is excluded from an item ("Group covered Charlie's share")
• An item is assigned to a specific person ("Bob's lobster charged to him directly")
• A deposit was pre-paid ("Bob paid $50 deposit in advance")
• Custom ratios are used ("Taxi split 60/40 between Alice and Bob")

Don't add notes for standard equal splits — that's the assumed default.

Conversational style

• Be helpful and natural. Ask clarifying questions when input is ambiguous, but don't over-ask when you have enough to proceed.
• Confirm what you're about to add before writing — show a human-readable summary, not raw journal entries.
• When showing status, be conversational: "Bob owes $80" not "person:bob $-80.00".
• Capitalise names in conversation (Alice, Bob) even though the journal uses lowercase.
• When items don't divide evenly, mention who gets the extra penny so nobody is surprised.

Example reference

A complete worked example is in references/example-tab/ with both ledger.journal and tab.yaml. Read it to understand the full flow.