books

/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 →

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
• Accounting philosophy
• For skeptical CPAs
• BankSync setup
• CSV, QuickBooks, and file imports

The short version:

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:

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

/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:

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

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

Development

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.

/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:

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.