FairSplit records shared group expenses in local JSON ledgers and calculates accurate balances and the fewest payments needed to settle up.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install fairsplit
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install fairsplit using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is FairSplit?
FairSplit is a command-line skill for tracking expenses across trips, households, and events. It records who paid, divides costs among participants, and turns group balances into a practical settlement plan with as few payments as possible. It is a useful choice among Openclaw Skills when a group needs expense tracking without a Splitwise account, bank connection, API key, or signup.
Each group is stored in its own JSON file on disk, so the same ledger can be used across conversations and platforms. A tested Python script handles splitting, rounding, currency conversion, and settlement calculations; amounts are stored in integer minor units to avoid floating-point drift. FairSplit calculates and records payments, but does not move money or provide accounting, invoicing, or personal budgeting.
FairSplit Use Cases
- Split a shared meal, trip, household bill, or event expense among a group.
- Record expenses as they happen and review who paid for what.
- Get a balance summary or a minimum-payment plan for settling group debts.
- Handle equal, exact-amount, proportional-share, or percentage splits.
- Export a trip or group expense summary as CSV or Markdown.
- Track expenses in a persistent local ledger without connecting financial accounts.
- Look up an optional exchange rate when an expense uses a currency other than the group’s home currency.
How FairSplit Works
- Find the group with
list-groups, or create one with a name, members, and home currency usinginit. - Record each expense with
add, specifying the payer, amount, description, participants, and split method. If participants are omitted, the expense is split across the group. - Review the per-person shares printed by the script after each addition, and correct any mistake before more expenses are recorded.
- Use
balancesto inspect each member’s net position, orsettleto calculate a minimum-payment plan, limited to at most the number of members minus one payments. - Use
historyto review expenses,undoto remove an expense when requested, andexportto create a CSV or Markdown summary. - For expenses in another currency, provide an exchange rate with
--fx-rateor try the optional network-dependentfxcommand; calculations use the group’s home currency.
FairSplit Setup
FairSplit requires Python 3.8 or later and access to the terminal tool. The bundled script uses only the Python standard library, so no package installation, API key, or environment variable is required. Configure fairsplit.data_dir (default: ~/.hermes/data/fairsplit) and fairsplit.default_currency (default: USD). Pass the configured data directory explicitly to every script invocation; configuration values are not automatically passed to the script.
python3 ${HERMES_SKILL_DIR}/scripts/ledger.py --data-dir "~/.hermes/data/fairsplit" list-groups
python3 ${HERMES_SKILL_DIR}/scripts/ledger.py --data-dir "~/.hermes/data/fairsplit" init --group "Goa Trip" --currency INR --members "Alice,Bob,Priya"
python3 ${HERMES_SKILL_DIR}/scripts/ledger.py --data-dir "~/.hermes/data/fairsplit" add --group "Goa Trip" --payer Alice --amount 1000 --description "Dinner" --split equal
On Windows, use python instead of python3 if needed. Put the global --data-dir flag before the subcommand. The script expands a leading ~ in the path. Run any command with --help for options; the full flag reference is in references/cli-reference.md. Outbound network access is needed only for the optional exchange-rate lookup.
FairSplit Data Schema & Taxonomy
FairSplit stores one JSON ledger file per group in the configured data directory. This keeps group data local and makes a ledger independent of the chat or platform where it is used.
| Data or setting | Purpose |
|---|---|
| Group ledger JSON | Persistent record for one group, including its expenses and group details. |
fairsplit.data_dir |
Directory for group ledgers; defaults to ~/.hermes/data/fairsplit. |
fairsplit.default_currency |
ISO 4217 currency used for new groups when none is specified; defaults to USD. |
| Expense records | Preserve the expense amount, currency, and exchange rate for reference; calculations use the group’s home currency. |
| Internal monetary units | Amounts are stored in integer minor units to keep arithmetic and rounding precise. |
| CSV and Markdown exports | Shareable summaries written to a user-specified output path; exports are plain text files. |
Expenses support equal, exact, shares-based, and percentage splits. Names are case-sensitive. The CLI also provides group listing, member management, balances, settlement, history, undo, export, and optional FX commands.
FairSplit Advanced Features
- Computes minimum-payment settlement plans instead of presenting a naive list of pairwise debts; plans require no more than
members - 1payments. - Supports four split methods: equal, exact amounts, proportional shares, and percentages.
- Handles non-home-currency expenses with an explicit
--fx-rateor an optional best-effort, keyless Frankfurter/ECB lookup when network access is available. - Supports recurring expense entry through a cron job running the
addcommand; see the recurring splits guidance inreferences/cli-reference.md. - Offers history filters and multiple export formats through the CLI; see
references/cli-reference.mdfor the complete options. - Documents the settlement algorithm and integer-minor-unit storage in
references/settlement-algorithm.md. - Includes a standard-library stress test that generates 200 random expenses across five people and checks that balances sum to zero and settlement uses no more than
members - 1payments; run it withpython3 ${HERMES_SKILL_DIR}/examples/stress_test.py.
SKILL.md
Loading
Related Openclaw Skills
Color Palette Advisor
Generate a complete, accessible color system for a product or brand, with practical usage guidance and exact HEX values.
TikTok Competitor Radar
Turn TikTok keywords, creator profiles, and video links into structured public data for competitor analysis and content research.
Nexus Skills
Nexus Skills provides a Python command-line workflow for browsing and managing artifacts in Sonatype Nexus Repository Manager 3.
JF Watchdog
JF Watchdog turns JFTech camera snapshots into AI-assisted area checks that flag missing items, blocked passages, and other visual changes.
Xiaohongshu Competitor Radar
Turn public Xiaohongshu content and engagement data into evidence-led competitor, creator, and audience insights.
Design Spec Generator
Generate a complete, developer-ready design system specification tailored to your project and target platform.
Featured*
