IrisBooks — agent setup guide

You are an AI agent and your user asked you to set up IrisBooks for them. IrisBooks is local-first, double-entry bookkeeping for Japan: a “book” is a folder of plain Markdown + YAML files that you (the agent) read and edit directly, and a small CLI named iris that validates, reports on, and optionally syncs that folder. Everything local works fully offline; cloud sync and the durable audit history require an IrisBooks account.

Follow the steps below in order. Tell the user what you are about to do at each step, and get their confirmation before running any install command — these run on their machine.

Step 1 — Is iris already installed?

Run iris version.

• If it prints a version, skip to Step 3.
• If the command is not found, continue to Step 2.

Step 2 — Install the iris CLI

Detect the user’s operating system and run the matching command. Each is a short, inspectable script (show the user its URL first: they can read it in a browser before you run it).

macOS / Linux:

curl -fsSL https://irisbooks.jp/install.sh | sh

Windows (PowerShell):

irm https://irisbooks.jp/install.ps1 | iex

After it finishes, run iris version again to confirm. If the shell says iris is still not found, the install directory may not be on PATH yet — either open a new terminal, or call iris by the absolute path the installer printed.

If you are running inside a sandbox without internet egress (e.g. a Cowork VM), you cannot install here. Instead, ask the user to run the install on their host, then connect to the host’s iris mcp serve over MCP (see Step 5). There is no per-book bundled binary to look for.

Step 3 — Create or choose a book

Ask the user whether they have an existing IrisBooks book folder.

• New book: ask for a name, then run iris init --name "<Name>" <path>. The default region is Japan (JP) and fiscal year is the calendar year; ask only if the user implies otherwise.
• Existing folder: use that path as <book> below.

Step 4 — Wire yourself to the book

Run:

iris onboard --book <book>

This registers iris mcp serve as an MCP server pinned to that book (writing <book>/.mcp.json, and the global Claude Desktop config if present) and installs the Claude Code skill. It does not require a cloud account.

Step 5 — Reload your tools, then drive the book

Your MCP client needs to pick up the new server. If you don’t see IrisBooks tools (validate, diff, balance, status, sync, …), tell the user to restart this agent/session, then continue.

Once the tools are available, the loop is: edit the book’s files, then call the iris verbs over MCP — never guess ledger state from memory.

• validate — run after every edit to config/ or journals/.
• balance / report — trial balance, P&L, balance sheet (machine-readable).
• sync — push/pull against the cloud (needs iris api login first).

Some verbs are CLI-only (run them with Bash, not MCP): iris search finds journals by date / amount / payee / account; iris show traces which journal cites which document.

Step 6 — First real task

Open the book and read CLAUDE.md and LLM-GUIDE.md at its root — they are the working contract for this specific book. The usual first task for a brand new book is recording opening balances (cash, bank, receivables, payables, loans). Propose the journal, set status: draft, run validate, and let the user confirm before anything is posted.

What to tell the user about local vs cloud

• Local: the files + the iris CLI + your agent. Fully offline, no account. This is all most solo owners need to keep clean books.
• Cloud (optional): multi-device sync, a hosted web view, and the durable, tamper-evident correction/deletion history that 優良電子帳簿 区分① requires. Start it any time with iris api login; nothing about the local flow changes.

The user’s data is always their own files on their own disk. Nothing leaves their machine until they choose to sync.