giltotherescue/books

# GitHub Repository: giltotherescue/books

**URL:** https://github.com/giltotherescue/books
**Author:** giltotherescue
**Description:** Bookkeeping for people who keep putting it off. Your AI agent keeps the books current and tax-ready — built for Claude Code and Codex.
**Homepage:** 
**Language:** Python

## Stats
- Stars: 0
- Forks: 0
- Open Issues: 0
- Commits: 23
- Created: 2026-06-13T02:41:06Z
- Updated: 2026-06-18T13:13:40Z
- Pushed: 2026-06-18T13:13:35Z

## README
# /books

Bookkeeping for people who keep putting it off. Your AI agent keeps the
books current and tax-ready — so you always know where you stand.

`/books` is agentic bookkeeping for Claude Code, Codex, and other AI agents.
It does the tedious work — set up the books, pull in bank and card activity,
categorize the repeat transactions, close the month, answer your questions, and
prepare the package your accountant needs. You only step in for the judgment
calls.

For everyday cash-basis bookkeeping, it is built to replace tools like
QuickBooks: nothing new to learn, far less to pay, and no vendor between you and
your own numbers.

No bloated accounting app. No spreadsheet archaeology. No managing bookkeepers
or outsourced cleanup projects just to stay on top of your numbers. The books
live on your machine, in files you can open and read.

**[Install for Claude Code or Codex →](#install)**

## What You Can Do

- Start books for a company in an empty directory.
- Keep the ledger as local plain-text files you own.
- Let an agent handle the monthly close workflow.
- Review unfamiliar transactions before they become trusted rules.
- Ask plain-English questions and get numbers from deterministic reports.
- Backtest against QuickBooks exports before trusting a migration.
- Generate a CPA package at tax time.

## Status

`/books` is beta software. Use it for cash-basis owner-operated businesses only,
review its output, and keep an accountant or tax professional in the loop.

`/books` is not tax, legal, accounting, payroll, inventory, or investment advice.
It does not replace professional review, and it is not designed for businesses
that need payroll, inventory, multi-user accounting controls, or full accrual
accounting.

## Start Here

If you want to use `/books` for a company, read:

- [How to do your books with `/books`](docs/doing-your-books.md)
- [Accounting philosophy](docs/philosophy.md)
- [For skeptical CPAs](docs/for-cpas.md)
- [BankSync setup](docs/banksync.md)
- [CSV, QuickBooks, and file imports](docs/imports.md)

The short version:

```sh
mkdir -p ~/Documents/books/acme-co
cd ~/Documents/books/acme-co
```

Then ask Claude Code or Codex:

> I want to set up books for this company here.

The `/books` skill routes the agent into setup. The first deterministic command
is usually:

```sh
books entity init . --name "Acme Co" --business-type consulting
```

Do not use the plugin source repo as a company books directory. Plugin upgrades
should never overwrite company books.

## Install

### Claude Code

```sh
/plugin marketplace add https://github.com/giltotherescue/books
/plugin install books
```

### Codex

This repo includes both Codex plugin metadata and a native Codex marketplace:

- `.codex-plugin/plugin.json`
- `.agents/plugins/marketplace.json`

From a fresh clone, add the repo marketplace in Codex:

```sh
codex plugin marketplace add /path/to/books-repo
```

Then enable/install the `books` plugin from that marketplace in the Codex app.

### Development

```sh
git clone https://github.com/giltotherescue/books books-repo
cd books-repo
pip install -e .
python3 -m unittest discover -s tests
```

The public command is `books`.

## Workflows

Start with `/books` or natural language like “do my books here.” That router
checks whether the current directory already has an entity and sends the agent to
the right workflow.

```text
/books
├── /books-onboard      set up a company, sources, and opening balances
├── /books-backtest     compare against QuickBooks exports before trusting it
├── /books-close        import activity, review unknowns, and finalize a period
├── /books-review       resume or work through queued transactions
├── /books-ask          answer questions from the ledger
└── /books-cpa-package  generate accountant exports
```

The agent workflows call the `books` CLI. They should not compute financial
totals themselves.

## Company Data

Each company directory contains its own books and generated state:

```text
acme-co/
├── entity.json
├── trust-policy.json
├── books.beancount
├── chart-of-accounts.beancount
├── audit-log.jsonl
├── staging/
├── review-queue/
├── learned-context/
├── ingestion/
└── reports/
```

`/books` stores company data locally in the company directory you choose. The
plugin does not host your books.

Credentials should live in `.env`, your OS credential store, or another local
ignored secrets file. The `books` command reads `./.env` from the current company
directory. Do not commit API keys, bank exports, QuickBooks exports, company
ledgers, generated reports, or entity directories.

## Contributing

The workflow skill names are prefixed, such as `/books-close`, so they remain
portable when copied into `.agents/skills`, `.codex/skills`, `.claude/skills`,
or another Agent-Skills-compatible library without plugin-level namespacing.

To add a data source adapter, create `src/bookkeeping/adapters/<source>.py`,
register the CLI subcommand in `src/bookkeeping/cli.py`, and declare the source
type in `entity.json`.

To add a chart-of-accounts template, add a template under
`skills/books-onboard/templates/`, register the business type in
`src/bookkeeping/entity.py`, and keep onboarding copy-once and non-destructive.

## License

MIT. See [LICENSE](LICENSE).