openbooks-agent

Cross-harness agent plugin that turns any coding agent into the treasurer for a family or club: record money in plain language, get the statements for a meeting, and never see a debit or a credit.

Built to the Open Plugins layout, so the same directory installs as a Claude Code plugin, as skills via skills, or by any harness that scans the standard component directories.

It talks to openbooks-api over that API's MCP endpoint — so the ledger rules stay in the database and the agent just drives it.

Install

As a Claude Code plugin

This repository is its own marketplace, so there's nothing else to add:

/plugin marketplace add hatchertechnology/openbooks-agent
/plugin install openbooks@openbooks

That brings the skills, the treasurer agent, the /openbooks:record and /openbooks:report commands, and the MCP server connection in one step.

As skills, in any of 75+ agents

npx skills add hatchertechnology/openbooks-agent --all

Pick a subset with --skill recording-money --agent cursor, or list what's there with --list. This installs the skills only — wire up the MCP server yourself (see below).

Any other Open Plugins host

Point it at the repository. Components live in their default locations, declared in .plugin/plugin.json.

What's in it

Component
skills/recording-money	Turns "we paid $45 for pizza from checking" into a balanced posting
skills/meeting-reports	Monthly, quarterly, or annual statements, written to be read aloud
skills/checking-the-books	Pre-meeting sanity check: duplicates, wrong periods, impossible balances
agents/treasurer.md	Subagent that does bookkeeping end to end
commands/record.md	/openbooks:record paid $45 for pizza from checking
commands/report.md	/openbooks:report Q2 2026
rules/ledger.mdc	The money invariants, for any harness that loads rules
.mcp.json	The openbooks MCP server

Connecting to your ledger

The MCP server defaults to http://localhost:38081/mcp, which is where just run puts the API. Override it for a different host:

export OPENBOOKS_MCP_URL=https://books.example.com/mcp

Six tools come across: list_accounts, account_balances, income_statement, balance_sheet, list_transactions, and record_transaction.

The design rule

Nobody using this should have to know what a debit is. The skills carry the double-entry mechanics — integer cents, signed entries summing to zero, which account takes the positive side — so the agent handles it and answers in the language the user asked in.

The ledger itself is the backstop: a deferred constraint trigger in Postgres rejects any unbalanced transaction, so a confused agent gets an error rather than writing crooked books.

Manifests

Three, because three ecosystems expect different filenames for the same information:

• .plugin/plugin.json — Open Plugins manifest
• .claude-plugin/plugin.json — Claude Code plugin manifest
• .claude-plugin/marketplace.json — one-entry marketplace pointing at this repo ("source": "./")

Keep the version and description in step across all three; claude plugin validate . and claude plugin tag both check that they agree.

Caveats

Early POC, matching the rest of OpenBooks: the API has no auth, so anything that can reach the MCP endpoint can write to the books. Don't point it at real money.