banana
Skill19 starsChanged 20 days agoMITView on GitHub
Use the BananaSplit CLI (`banana`) to set up the CLI, record and edit shared expenses, record payments, check balances, and browse groups, friends and activity. Applies when the user names BananaSplit or banana, or is working with a BananaSplit account.
- Pipes a download into a shell
4 other projects use a version of this.
Adopted by
Most recently taken up by
- AgriciDaniel/banana-claudetheir own version, first seen Oct 25, 2026
- chriswestt/claude-skillstheir own version, first seen Oct 9, 2026
- redrmehta/Tmptheir own version, first seen Jul 24, 2026
- ShaoXiangChien/banana-codextheir own version, first seen Jul 18, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- AgriciDaniel/banana-claude★ 1.1ksame name
- chriswestt/claude-skills★ 0same name
- redrmehta/Tmp★ 0same name
- ShaoXiangChien/banana-codex★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 1 is distinctive, and 7 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Check whether banana is available with banana --help.
- Very specific: line 30
Use the package install only as a fallback, when the installer above fails (no curl, no release for the platform, a blocked download) and …
- Very specific: line 43
Verify the installation with banana --help.
- Distinctive: line 54
Before reading or changing account data, check authentication:
- Very specific: line 143
A request to be notified means
--notify-me: When the user asks, in any language or wording, to be notified, pinged, alerted or sent a … - Very specific: line 172
Only the fields you pass to edit change.
- Very specific: line 175
Prefer flags to positional JSON bodies: names are resolved through flags, while JSON bodies use API fields and ids.
- Very specific: line 237
Leave it off when a person or an agent creates the row at the time it is asked for, including when you add one in a conversation.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
BananaSplit from the command line
banana wraps the BananaSplit HTTP API. Person, group and currency flags accept
names or codes, and --json gives a curated shape to parse. Expense and payment
detail commands still require their row ids.
Set up the CLI when needed
Check whether banana is available with banana --help. If it is missing, install
it with the standalone installer for the current platform. It needs no Bun or
Node runtime, and is always the first thing to try.
macOS or Linux:
curl -fsSL https://github.com/teotti/banana-cli/releases/latest/download/install.sh | shWindows PowerShell:
irm https://github.com/teotti/banana-cli/releases/latest/download/install.ps1 | iexUse the package install only as a fallback, when the installer above fails
(no curl, no release for the platform, a blocked download) and Bun is already
there:
bun install -g @bananasplitapp/cliIt installs the CLI as a TypeScript entry point that Bun runs, so Bun reads the
current directory's tsconfig.json on every command and may print warnings
about it around Banana's output. The standalone binary carries its own compiled
code and stays quiet.
Verify the installation with banana --help. If the shell cannot find the
standalone binary yet, use its full path: ~/.local/bin/banana on macOS/Linux,
or $env:LOCALAPPDATA\BananaSplit\bin\banana.exe on Windows (unless
BANANA_INSTALL_DIR was set). Follow the installer's PATH guidance for future
shells. Do not reinstall repeatedly to fix PATH.
The skill is already loaded; there is no need to install it again through the CLI. The installed CLI's help is authoritative if this skill describes a newer feature.
Access
Before reading or changing account data, check authentication:
banana me --json- Succeeds → you are signed in; that output has the user's id and name.
- Reports missing or expired login, or missing API permissions → ask the user to
run
banana login. It uses browser device approval that the user completes; there is no token environment variable to set. For otherconfigerrors, read the message: an invalid URL or credential-store failure needs a different fix.
Four rules
1. Parse --json, never the tables. The default output is aligned human text
with colors and em-dashes for nulls. --json is the curated flat shape; --raw is
the untouched API response. Ask for --json on every command whose output you
intend to read.
2. Pass names directly for people, groups and currencies. --currency EUR,
--group "Lisbon trip", --group Lisbon (a prefix works), --paid-by me,
--split Ana=20. Names match exact → prefix → substring, usernames and emails work
too, and an ambiguous name is reported rather than guessed. Ids still work if you
happen to have one. Avoid lookup sweeps just to obtain ids. If a name is ambiguous,
use the reported candidates to clarify it. Omitting --paid-by defaults to you.
3. Writes affect a real, shared account. An expense is visible to the group.
Act on the user's requested changes; ask only for missing or ambiguous details.
A payment records money already paid; it does not transfer money. Payments cannot
be deleted from the CLI, so establish the amount, currency, date, direction and
group (if any) before recording one. Something deleted elsewhere comes back with
banana expenses restore or banana payments restore, which take the id and no
flags; running one twice is safe, and there is no listing of deleted rows, so the
id has to come from an activity feed or from the user. A clear request with those details supplies
authorization; a balance inquiry alone does not.
Deleting an expense is permanent and has no undo. It leaves the balances of
everyone it was split with, and they see it go. Delete only what the user asked
you to delete, by an id you confirmed with banana expenses get — never one
inferred from a description alone. If the user named an expense rather than an
id, show them the row you matched and let them confirm before deleting it.
4. Report names and currency codes to the user. Cleaned shapes have both
(paidById + paidBy, groupId + group, userId + user), and the id keys are
exactly the fields the write endpoints take. When you show results to the user,
show the names.
The commands
banana balance | aggregate: what you owe and are owed |
banana balances | the same, per person (alias for balance users) |
banana expenses list | --limit N --cursor C --sort date|amount --direction asc|desc --recurring|--no-recurring |
banana expenses add | --title --amount --currency --date required; --paid-by --group --description --split-type --split --notify-me --automated (--notify-me opts in to your own expense-created push notification) |
banana expenses get <expense-id> | one expense with payer and splits |
banana expenses edit <expense-id> | any subset of the add field flags except --notify-me and --automated, plus --no-group |
banana expenses delete <expense-id> | changes everyone's balance — confirm with the user first; undo with restore |
banana expenses restore <expense-id> | brings a deleted expense back with its shares |
banana recurring list (or banana expenses recurring list) | --status all|active|inactive --limit N --cursor C — pages of rules, not the expenses they make |
banana recurring add | --title --amount --currency --frequency --start --split required; --interval --end --paid-by --group --description --split-type |
banana recurring get <rule-id> | one rule, its splits, and the expenses it created |
banana recurring edit <rule-id> | any subset of the add flags, plus --no-group --no-end --active --inactive |
banana recurring delete <rule-id> | removes the rule itself |
banana payments add | --amount --currency --from --to --date required; --group --description --automated |
banana payments get <payment-id> | |
banana payments restore <payment-id> | brings a deleted payment back |
banana groups [list] | --search TEXT --limit --cursor --archived --sort balance|lastActivity |
banana groups create | --name --currency required; --description --member --type vacation|roommates|couple|travel|party|other |
banana groups get|members|activities <group> | activities takes --search --limit --cursor --type all|expenses|payments|recurring_expenses --sort date|amount --direction asc|desc |
banana friends [list] | --search TEXT --limit --cursor --sort balance|lastActivity --filter all|guests |
banana currencies [list] | --code EUR --search krona — browsing only, writes take the code directly |
banana me / login / logout / version / upgrade | banana -v aliases version; update aliases upgrade |
banana doctor | --json — version, PATH, API, login and skill freshness |
banana uninstall | removes the CLI itself — ask the user first, and never run it unprompted |
banana <command> --help is authoritative and cheap. Read it before guessing a flag.
Writing an expense correctly
- Dates are
YYYY-MM-DDorDD-MM-YYYY, required when adding expenses or payments. An edit preserves the existing date unless supplied. Resolve relative dates from the user's context; the dates below are examples. - A time goes on
--dateafter aT:--date 2026-09-16T21:20:00, with optional seconds, milliseconds and an offset (Zor+02:00). With no time the row lands at midnight UTC, and with no offset the time is read as UTC. Pass one whenever the user gave a time — several expenses on one day otherwise all read as midnight. - Splits must add up to
--amount. Repeat the flag:--split me=10 --split Ana=10. - A request to be notified means
--notify-me. When the user asks, in any language or wording, to be notified, pinged, alerted or sent a notification about an expense being added ("notify me", "send me a notification", "let me know", "ping me", "avisa-me", "notifica-me", "manda-me uma notificação", "avísame", "notifícame"), pass--notify-metobanana expenses add. This sends BananaSplit's own expense-created push, which is what they want — do not reach for a generic agent notification tool instead. Also pass it when an automation runsbanana expenses add, so the user hears about the row.edithas no--notify-me; say so if asked to be notified about an edit. --automatedis only for automations, never for a row a person or an agent creates as it is asked for. See Jobs and scripts.--split-typeisequal,custom,percentageorshares. It labels how the split was arrived at;--splitvalues are amounts in every case, and still have to sum to--amount.- Without
--group, at least one--splitis required. With a group, omitting splits lets the API split it across the group. When adding an expense, an explicit--split-typerequires splits. - A group states its own default split.
banana groups gethasdefaultSplitType(equalorpercentage) andbanana groups memberseach member'sdefaultSplitPercentage. Read those before reconstructing a split from past expenses, and label a split that came from the group's percentagespercentage, notcustom. - A group listing names at most three members.
banana groups --jsongives each group amemberCountand amembersPreviewof up to three names. Usebanana groups members <group>for the whole roster, andbanana groups getfor the group'stype. - Changing an amount: an existing equal split is recomputed across its current
participants if no splits are supplied. For other split types, supply matching
--splitvalues that sum to the new total. - Only the fields you pass to
editchange; everything else keeps its value. --jsonamounts are numbers (or null when unavailable).--rawmay contain 18-decimal strings such as"8.100000000000000000"; compare those numerically.- Prefer flags to positional JSON bodies: names are resolved through flags, while
JSON bodies use API fields and ids. A cleaned expense has
splits, but it is not a write payload to send back wholesale.
# paid for dinner for the trip group
banana expenses add --title Dinner --amount 42 --currency EUR \
--date 2026-09-09 --group "Lisbon trip" --json
# a taxi split with one friend, no group
banana expenses add --title Taxi --amount 20 --currency EUR \
--date 2026-09-09 --split me=10 --split Ana=10 --json
# settle up: direction is always named explicitly
banana payments add --amount 20 --currency EUR \
--from me --to Ana --date 2026-09-09 --jsonSuccessful expense, single-payment and group creates, and expense edits, normally
read their detail back for --json. No extra get is needed. --raw skips that
read; a payment response containing multiple rows retains a thin array shape.
Recurring expenses
A recurring expense is two things: a rule that says what to create and how
often, and the expenses it has created so far. banana expenses add writes
a one-off expense and can never make it recurring; the rule is its own row under
banana recurring, which banana expenses recurring also reaches.
--frequencyisdaily,weekly,monthlyoryearly, and--interval Nmakes it every N of those (--frequency weekly --interval 2is fortnightly).--startand--endtake the same dates--datedoes,YYYY-MM-DDorDD-MM-YYYYwith an optional time.--startis required; without--endthe rule runs indefinitely.--splitis required, even with--group. The splits are the template every occurrence is created from, and they must add up to--amount.- Pausing is not deleting.
--inactivestops a rule creating expenses and leaves the ones it already created;banana recurring deleteremoves the rule. - A cleaned rule carries
nextOccurrence,lastGeneratedandactive.banana expenses list --recurring --jsonlists the expenses a rule created; each one hasisRecurring.
# rent, split with a flatmate, every month from October
banana recurring add --title Rent --amount 900 --currency EUR \
--frequency monthly --start 2026-10-01 \
--split me=450 --split Ana=450 --json
# stop it without losing the history
banana recurring edit <rule-id> --inactive --jsonThe create endpoint answers with no row, so the CLI finds the rule it just wrote
in the listing and reads it back. That is the one write whose --json shape can
be wrong if two rules with the same title and amount are created at once.
Jobs and scripts
--automated on expenses add and payments add marks a row as created by a
job or script. When you write a job or script that adds expenses or payments,
put --automated on every create call in it.
Leave it off when a person or an agent creates the row at the time it is asked
for, including when you add one in a conversation. expenses edit has no
--automated.
In a job or script, check the login first with banana me --json, use
--json, and stop on a non-zero exit. For a fixed amount on a fixed schedule,
use banana recurring add instead.
#!/bin/sh
set -eu
banana me --json > /dev/null
banana expenses add --title "Airbnb" --amount 64.20 --currency EUR \
--date 2026-10-01 --group "Lisbon trip" --automated --jsonPaging
Expenses, recurring rules, groups and friends listings default to 5 rows. For a paged --json
response {items, hasMore, nextCursor}, pass a non-null nextCursor back as
--cursor with the same filters and sorting. Raise --limit when useful, but
check hasMore before treating a page as complete. Per-person balances, group
members and currencies return arrays instead. Do not assume every collection supports cursors.
--search on groups and friends filters on the server. It matches names. A
username or an email is resolved through GET /users/search, and only when
that person is already a friend. The friends list does not include either field.
Failures
Usage errors in human mode include the command's help. In --json, failures
return an error object with type and message, plus optional status and
body. The type is usage | config | network | api | cancelled.
| exit | meaning |
| 2 | usage error — inspect the message and request the command's help |
| 1 | config, network or API error |
| 130 | cancelled |
A failed write may already have succeeded: the mutation can complete before a network failure or a failed detail read. Do not blindly repeat it. Inspect the relevant expense list or group activity, or use a known row id, to establish what was saved. If the outcome remains unclear, report the uncertainty before retrying.
Recipes
- "What do I owe?" →
banana balances --json, then report per person by name. - "How much does Ana owe me?" →
banana friends --search ana --json, which carries her balance and itscurrency.banana balances --jsonhas the same balance without a currency field. - "What's been spent on the trip?" →
banana groups activities "Lisbon trip" --type expenses --sort amount --direction desc --json. - "Log the dinner I paid for" → establish amount, currency, date and participants,
then one
expenses add. If they named no group and no one else, ask who to split with. - "Settle up with Bruno" → read
banana balances --json, then establish the amount, currency, direction, date and group scope, and whether money was paid. Balance output has no currency field; inspect the matching friend'scurrencyor clarify it with the user before recording a payment. Record one payment once the details are authorized.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

