Guide

Using Tally with AI assistants

#How It Works

Tally is a rule engine that classifies transactions. The AI assistant is the operator that writes the rules. Together they create a feedback loop:

1. Tally finds uncategorized transactions
2. AI identifies the merchants and writes categorization rules
3. Tally applies rules and finds remaining unknowns
4. Repeat until everything is categorized

#Supported AI Assistants

Any AI agent that can run command-line tools will work with Tally.

#Starting a Session

After setting up your budget folder, open it in your AI assistant and tell it what to do:

The agent will run tally workflow to understand the current state and follow the instructions.

#The Workflow Command

The tally workflow command is context-aware. It detects your setup state and shows relevant next steps:

No data sources configured

tally workflow

No data sources configured yet.

To add a data source:
1. Run: tally inspect data/yourfile.csv
2. Add the suggested config to settings.yaml

Unknown merchants found

tally workflow

Found 47 unknown merchants.

Run: tally discover --format json
Then add rules to config/merchants.rules

Ready to generate report

tally workflow

All transactions categorized!

Run: tally up

#Key Commands for AI Agents

Discover unknown merchants

tally discover --format json

Returns uncategorized transactions with suggested patterns. The AI uses this to write rules.

Inspect CSV structure

tally inspect data/chase.csv

Analyzes CSV structure with column type detection (dates, currency, numbers, categorical). Shows samples for both positive and negative amounts to help understand sign conventions.

Explain a classification

tally explain Netflix -vv

Shows why a merchant is classified a certain way, including which rule matched. Supports combined filters:

tally explain --category Food --month Jan
tally explain --tags business --month 2025-01

Debug configuration

tally diag --format json

Validates configuration and shows any errors.

Run full analysis

tally up --format json -v

Returns complete analysis with classification reasoning.

#Writing Rules

When the AI finds unknown transactions, it adds rules to config/merchants.rules:

[Netflix]
match: contains("NETFLIX")
category: Subscriptions
subcategory: Streaming
tags: entertainment, recurring

[Whole Foods]
match: contains("WHOLEFDS") or contains("WHOLE FOODS")
category: Food
subcategory: Grocery

See the Reference for full syntax.

#Using Transforms

Transforms are top-level assignments in merchants.rules whose left side starts with field.. You can optionally include an @transforms line as a human-readable separator, but it isn't required by the parser.

Example: add a fee column to the transaction amount.

@transforms
# Strip $/commas from fee, then add to amount
field.amount = field.amount + regex_replace(regex_replace(field.fee, "\\$", ""), ",", "")

# Clean descriptions
field.description = regex_replace(field.description, "^APLPAY\\s+", "")

#Customizing Categories

Tally doesn't have predefined categories. You define them in your rules:

• Category - Primary grouping (Food, Transportation, Bills)
• Subcategory - Secondary grouping (Grocery, Rideshare, Utilities)
• Tags - Labels for filtering (business, reimbursable, recurring)

Tell the AI your preferred structure and it will use it consistently.

#Generating Reports

Once transactions are categorized:

tally up

This generates an HTML report with:

• Monthly spending breakdown
• Recurring expense detection
• Category summaries
• Transaction search and filtering

#Iterating

As you review the report, you might want changes:

The AI updates the rules, and you can regenerate the report.