# Tally: a local rule engine for bank transaction categories

> Tally is a Python command line tool that classifies bank transactions against rule files you write, and it is designed to be driven by an AI assistant rather than used directly. It suits someone who wants their spending categorised without sending their financial data to a service, and it is a beta project with a small dependency list.

**davidfowl/tally** — Let agents classify your bank transactions.

- Repository: https://github.com/davidfowl/tally
- Website: http://tallyai.money
- Stars: 1,168 · Forks: 100
- Language: Python
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/davidfowl-tally

## A rule engine with an agent in front of it

Tally is described in the README as a local rule engine for transaction classification, paired with an AI assistant to eliminate the manual work. The project description phrases it differently, as letting AI classify your transactions with LLM powered spending categorization, and that difference in emphasis is the most interesting thing about the design.

The README's framing is the more accurate one for an engineer. Tally itself does the classifying, against rules you write. The AI assistant is the thing that writes or edits those rules, by looking at transactions that have not been categorised yet and deciding what should match them. That is a very different risk profile from sending your data to a model, because the model can be asked to propose a rule rather than to answer with a category, and a rule can be read before it takes effect.

The tool works with Claude Code, Codex, Copilot, Cursor, or any command line AI agent, which is a deliberately broad list. The one instruction in the quick start is the whole interface: tell your AI assistant to use tally to categorize my transactions.

The other thing worth noting is the repository layout. There is an.mcp.json file at the top level, and the optional development dependencies include pytest-playwright, which suggests the repository is set up for agent tooling as well as for the command line.

The licence is MIT, the project is by David Fowler, and the classifier in the manifest says Development Status:: 4 - Beta. The last push to the main branch was on 2026-05-18, with a development build tagged on the same day and v0.1.321 from January 2026.

## Installing it, and creating a budget folder

The install is a script, one per platform family.

For Linux and macOS:

```bash
curl -fsSL https://tallyai.money/install.sh | bash
```

And for PowerShell:

```powershell
irm https://tallyai.money/install.ps1 | iex
```

Both are pipe-to-shell installs, which is worth pausing on for a tool whose input is your financial data. The alternative is visible in the project manifest, which is a normal Python package with a console script entry point of tally = tally.cli:main, a single runtime dependency of pyyaml at 6.0 or newer, and a build backend of hatchling. The package name is tally, it requires Python 3.10 or newer, and the wheel ships src/tally. The optional build extra pulls in pyinstaller, which is how the standalone binary is produced.

The quick start then creates a budget folder and asks the tool what to do next:

```bash
tally init ./my-budget      # Create budget folder
cd my-budget
tally workflow              # See next steps
```

That second command is the design in miniature. tally workflow shows context-aware next steps, meaning the tool knows where you are in the process and tells you what to do from there, which is a lot more useful than a generic help screen when the workflow involves an agent that has to be told what to do.

The documentation is split into four pages, which is a reasonable size for a tool this focused. There is a quick start to get running in five minutes, a guide on using Tally with AI assistants, a reference covering merchants.rules and views.rules syntax, and a formats page covering settings.yaml and CSV format strings.

## Seven commands, and what each one is for

The command table is short enough to take in at a glance, and each command maps to a different stage of the work.

tally init creates a new budget folder. tally workflow shows context-aware next steps. tally up generates an HTML spending report. tally discover finds uncategorised transactions, which is the command that drives the whole agent loop, since it is the queue of work waiting to be ruled on. tally explain explains merchant classifications. tally inspect analyses CSV structure. And tally reference shows the full syntax reference.

Three of those deserve a note.

tally discover is the pivot of the design. Rather than the tool trying to categorise everything automatically on import, it surfaces what it does not know and leaves that to the agent and to you. The agent proposes a rule for a batch of them, you review, and the rule is saved. That is a workflow where the automation is safe by construction, because a rule is an artefact you can inspect.

tally explain is the counterpart to that. When a transaction is categorised and you do not agree, the tool can tell you which merchant rule matched, which turns an argument with a black box into a question about one line of YAML.

tally inspect is a preparation step. Bank exports differ, and some are messier than others, so being able to ask the tool what shape your CSV is before you import it saves a class of confusing failures.

And tally up produces an HTML report, which is a plain file you can open or share, with no server and no account.

## One runtime dependency, and a repo shaped for agents

The dependency list in the project manifest is remarkably small. The only runtime dependency is pyyaml at 6.0 or newer, and the development extras are pytest at 7.0 or newer with pytest-playwright at 0.4.0 or newer, and pyinstaller at 6.0 or newer for the build. The classifiers cover Python 3.10, 3.11 and 3.12, and the topic is Office/Business, Financial, Accounting.

One dependency is a meaningful signal for a tool in this category. A rule engine that reads YAML and writes reports does not need a data frame library, an HTTP client, or a model client, because none of those are part of the classification. Whatever talks to the model is the agent's own tooling, which lives outside this package. That is what makes the README's claim that this is a local rule engine credible rather than a description of a thin wrapper around an API call.

The repository layout shows the same commitment to agent interoperability. There is an .mcp.json at the root, an AGENTS.md and a CLAUDE.md, a .vscode/ directory, a config/ directory, a docs/ directory, and a src/ directory. Two different agent instruction files is a small thing that says the author expects the tool to be used by more than one kind of assistant, and the .vscode directory suggests Copilot is a first-class target rather than an afterthought.

The build uses uv, with a uv.lock at the top level, and the pytest configuration sets the test path to tests/ with src/ on the Python path, plus a playwright marker for the tests that need browser automation. The marker definition is explicit about which tests are browser tests, which is a small quality signal in a project where the test suite may otherwise be unclear about what it needs.

## What to verify before you trust it with your statement

There are a few things worth checking that the README leaves implicit.

The first is what the CSV actually contains. A bank transaction export carries merchant names, amounts, dates and often a raw description string that can include a branch identifier, an authorisation code and sometimes a partial card reference. The tool's job is to read that, and the format pages cover CSV format strings and settings.yaml, but the classification rules match on merchant names, so what your export puts in that column determines how much of your history gets categorised correctly on the first pass. The inspect command exists for exactly this, and running it before importing is the cheap way to find out.

The second is where the rules live and who can edit them. The reference page covers merchants.rules and views.rules syntax, and both are files in your budget folder. A budget folder is a directory on your machine, so it inherits your machine's backup and sync behaviour, and if you keep it in a synced folder, your rules go with it.

The third is the reports. tally up generates an HTML spending report, and an HTML file containing your categorised spending is a document you would rather not leave lying around or paste into a chat. It is worth knowing where it lands before you generate the first one.

The fourth is the agent's role. The instruction to give your assistant is to use tally to categorize my transactions, and a capable assistant will read your budget folder, which means the rules and the data are both in its context. If that is not what you want, the alternative is to run the commands yourself and review each rule. The project is MIT licensed and the rules are plain YAML, so nothing prevents that.

## Conclusion

Adopt Tally if you want your transaction history categorised by rules you can read and edit, because the classification lives in plain YAML files rather than in a model's head, which means you can see why a transaction landed in a category and change it. Do not adopt it as a budgeting system, since it is a classification and reporting tool with no ledger, and treat the AI assistant as an assistant rather than the engine, since the README describes Tally itself as a local rule engine. Before you import your data, read the reference for merchants.rules and views.rules syntax, and check what your export contains, because a CSV of your transactions is the most sensitive file you are likely to have on a development machine.

## FAQ

### What does Tally do with my bank transactions?

Tally classifies transactions against rule files you control, merchants.rules and views.rules, and can generate an HTML spending report. The README describes it as a local rule engine paired with an AI assistant, so the categorisation itself is rule based and the assistant is used to propose rules for uncategorised transactions.

### How do I install Tally?

On Linux and macOS, `curl -fsSL https://tallyai.money/install.sh | bash`. On PowerShell, `irm https://tallyai.money/install.ps1 | iex`. The project is also a Python package requiring Python 3.10 or newer, with a console script entry point of tally and a single runtime dependency on pyyaml.

### Which AI assistants does Tally work with?

The README says it works with Claude Code, Codex, Copilot, Cursor, or any command line AI agent. The repository includes an.mcp.json configuration, plus AGENTS.md and CLAUDE.md instruction files and a.vscode directory.

### What are the main Tally commands?

tally init creates a budget folder, tally workflow shows context-aware next steps, tally up generates an HTML spending report, tally discover finds uncategorised transactions, tally explain explains merchant classifications, tally inspect analyses CSV structure, and tally reference shows the full syntax reference.

## Sources

- [davidfowl/tally on GitHub](https://github.com/davidfowl/tally)
- [License: MIT](https://github.com/davidfowl/tally/blob/main/LICENSE)
- [Project website](http://tallyai.money)
- [README](https://github.com/davidfowl/tally/blob/main/README.md)
- [Releases](https://github.com/davidfowl/tally/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/davidfowl-tally