Clawback

References

• references/setup.md — installation and first-run setup
• references/ops.md — day-to-day operations and troubleshooting

Quick Command Reference

# Create a trip
clawback handle $CHAT_ID "kai trip Greece Vacation base EUR"

# Add expense
clawback handle $CHAT_ID "kai add dinner €120 paid by Dan"

# Check balances (free, instant)
clawback handle $CHAT_ID "kai balances"
clawback handle $CHAT_ID "kai balances in USD"

# Settle a debt
clawback handle $CHAT_ID "kai settle Sara paid Dan €40"

# Undo last action
clawback handle $CHAT_ID "kai undo"

# Full summary
clawback handle $CHAT_ID "kai summary"

Behaviour Rules

1. Never fabricate balances. Always call clawback handle for balance/summary queries.
2. Pass the raw user message to clawback handle — don't rewrite it. The parser is regex-based and handles EN + Hebrew natively.
3. Relay the output verbatim to the user (it's already template-formatted).
4. Use the correct chat_id — different groups are separate ledgers.
5. Don't call Clawback for casual conversation — only invoke on expense-related messages.

Chat ID Convention

For Telegram: use the numeric group chat ID (e.g. -1001234567890). For WhatsApp: use the group JID (e.g. [email protected]).

Store the active trip mapping in Clawback's state (~/.clawback/active.json); it persists across sessions.

Error Handling

If clawback returns an error:

• Check that the trip is initialized (kai trip <name> first)
• Verify participants are in the trip (kai who)
• For Sheets errors, check gog auth: gog auth status
• See references/ops.md for common issues