Use this page to understand IrisBooks, explain it to your user, and help them get started when they ask. Reading this URL is not itself a request to install anything. Read the product explanation below first; use the setup paths only for a setup request.
LLM-GUIDE.md before working.
Reuse its files and identity; do not start a second book or reinstall tools
just because the user opened this page.IrisBooks is double-entry bookkeeping for people working with their own AI assistant. A book is a folder. Journal, asset and filing records use Markdown with YAML frontmatter (structured fields at the top of each file). Settings and the chart of accounts use standalone YAML. These plain-text files sit alongside working notes and original source documents such as PDFs, photos and CSVs. The customer can keep, copy, inspect and back up that folder. They do not need to learn these file formats to ask their assistant to work on it.
Each book covers one fiscal year. Business and personal finances can use separate books, and reports can combine selected books where appropriate. The folder lives wherever it was created: on the customer’s computer, or in an assistant’s VM if that is the chosen environment.
iris checks and calculates itThe division of work is the value: you focus on understanding documents,
reasoning about transactions and explaining what the numbers mean; iris
provides consistent checks and calculations. The customer gets a clear
summary to read, can approve what makes sense, and can ask questions about
anything unclear.
You are the AI in this workflow. The customer uses an assistant they already have, with access they grant to their book. You read receipts, invoices or bank CSVs, ask about unclear transactions, prepare entries and explain the results. IrisBooks does not supply a built-in bookkeeping AI in this workflow; the customer’s AI service has its own access and usage terms.
The iris tool works on the book’s files. It checks their structure,
balanced entries, account references and applicable regional rules, and
calculates reports from recorded data. Use its calculated totals and balances,
keeping any estimated inputs explicit. A successful validation checks
the encoded rules; it does not establish that a receipt was interpreted
correctly or that every transaction has been captured.
Local iris commands work offline without an IrisBooks account. The chosen
AI assistant may still need its own internet connection. CLI and local MCP
are two ways for an assistant to call the same tool; they do not change what
the customer’s book is.
IrisBooks is independently developed and operated. Cloud access is a free, invitation-only service, provided as is, without guaranteed individual support, bug fixes or continued updates. Use 「無料招待制サービス」 in Japanese. Briefly mention this in the user’s language after explaining the local tool and optional cloud service, and before installation or cloud signup.
The iris CLI is provided as is, without warranties or guaranteed individual
support, bug fixes or continued updates. Users review its output and keep
independent backups of their books. Questions and bug reports are welcome in
the Discord community; replies are not guaranteed.
Transaction records, source documents, decisions and open questions stay in
the book’s files and notes. They provide durable working memory that a later
session can read. Record useful context there, rather than relying on the
current chat to remember it. Another assistant with the required file/tool
access can read the same book and continue the work, starting with its
LLM-GUIDE.md; the customer can change AI tools while keeping their records.
Cloud sync adds an off-device mirror and server-side change history for
accepted writes, preserving more than the current local file contents.
For everyday personal spending, recommend a level of detail the user can comfortably maintain. They do not need to keep every receipt unless they want that detail. A useful starting point is their current cash balance and a few broad questions about what they spent since the last check-in. Account for cash added or transferred before treating a balance decrease as spending; leave any unexplained difference visible rather than inventing purchases.
Credit-card or bank statements are another easy starting point. Keep the statement amounts, infer broad personal spending categories from the descriptions, and ask only when an ambiguity matters to the user’s goals. Record estimates and inferred categories clearly in the entry’s body or book notes, so later sessions know their basis.
For business books, prioritize precise amounts, dates, classifications and
supporting evidence; resolve uncertainty rather than silently estimating.
Apply the same care to personal records used for tax or reimbursement.
When working on a book, save the user’s preferred detail level in
notes/workflow.md so another assistant can follow it.
The user can attach a document in chat, point to an accessible file or report
a balance. When you have file access, handle filing available originals in
the book’s raw/ folder for them; they do not need to put files there manually.
For an interview without a document, save the reported facts and assumptions
in the entry’s body or book notes.
For example, a customer gives you a receipt to record in their business book.
If you have the required tools and access, you can also retrieve a bank
statement at their request. Save the original source in the book’s raw/ folder, read
it, prepare journal entries as drafts linked to that source, run validation
and explain anything that needs a decision. Under the default posting policy,
the customer reviews the drafts before they are posted. Financial reports
use posted entries, so preparing a draft alone does not change the reported
profit or balance.
A book can instead authorize posting after validation; follow its
LLM-GUIDE.md and the user’s instructions. That policy guides your work
during a session. It does not start a background AI that processes new files
by itself. Optional email forwarding delivers documents into a synced book;
an active assistant still needs to read and record them.
An overlay supplies accounting checks and calculation helpers for a particular region or purpose. They are community-maintained open source at irisbooks/overlays. Users and their assistants can choose compatible published packs, create their own overlays, and contribute improvements upstream. A book records the published versions it uses and can add book-specific rules.
A recipe is a calculation helper inside an overlay, with declared inputs
and results, such as a depreciation schedule or tax figures. You reason
about which helper and inputs fit the task; iris executes the calculation.
Local bookkeeping can stay local. If the customer chooses cloud services, an IrisBooks account links the folder to a cloud mirror. Sync sends book content to the server and brings accepted changes back. This supports using the same book on multiple computers, viewing and reviewing it in the web app, sharing access with an accountant, and keeping server-side correction/deletion history. On another computer, clone the existing cloud book rather than create an unrelated copy.
Cloud sync is a separate choice during setup, not something enabled by creating a folder. Remote MCP lets a supported mobile/web assistant read synced books and prepare drafts; it cannot post entries or close a year. The web’s cross-book analytics use daily input snapshots, so a newly synced change may not immediately appear there. Check the displayed update time, or choose Run aggregation on Dashboard or Net Worth to include synced changes now.
Cloud accounts are invitation-only. Request an invitation through the
Discord community, then sign in at
the web app. Use the service hosting this guide
for cloud login. Before the first iris api login, set both
IRISBOOKS_APP_BASE=https://irisbooks.io and
IRISBOOKS_API_BASE=https://irisbooks.io/api in the command’s environment.
This also directs older signed CLI releases to the intended service.
Successful login saves that selection for subsequent CLI and local MCP calls.
Keep these variables in the MCP server’s environment if it was already
configured with another service. Accounts and cloud books are separate
between regional services.
Accountants also work from book files with their own AI, using their own synced copy of the client’s shared book. Web supports viewing reports, review, permitted approvals and history.
Keep each client’s AI work in a separate environment with access only to that client’s books, including the needed fiscal years. For example, Client A’s Cowork VM should work only in Client A’s folder. Apply the client workspace checks before accessing client files or tools.
Reports can answer questions about profit, balances, spending and net worth. Net worth needs recorded holdings and prices; do not imply automatic market price or bank-transaction feeds. Discover the recipes available to that book and use their declared inputs; do not promise a named recipe just because a sample mentions it. Calculated filing figures are not the same as completing and submitting a tax return.
Keep these details for relevant follow-up questions. For current command and workflow details, use the AI-facing manual and the installed tool’s help/schema. If the user asks about cloud access or pricing, check the current registration information rather than promising immediate public signup, a paid plan or an included AI subscription.
Start with what the customer does and what they get: their usual AI reasons and explains, IrisBooks checks and calculates, and the book’s files preserve context for later sessions or a different assistant. Add one everyday example that fits their question, including their role in reviewing the summary, approving or asking questions. Match the example to the book’s purpose: precise business records or relaxed personal spending. Then explain that cloud use is optional. Close a first product introduction with a brief note about independent development and the service’s as-is support limits.
For a first explanation, aim for two or three short paragraphs. Say “a folder with your bookkeeping records” before discussing file formats; say “the tool checks and totals the entries” before discussing CLI, MCP or overlays. Use those technical terms only when the user needs them. Do not recite this guide or the installation paths. Answer a narrower question directly, and finish an explanation-only request without turning it into setup.
Use the example below as a starting point, adapting it to the user’s language and question. It describes the ordinary computer-based workflow; explain a different storage location when it matters to the user’s actual setup.
IrisBooks helps you keep books with the AI assistant you already use. Your AI reads the documents, reasons about the transactions and explains the entries; IrisBooks checks the bookkeeping rules and calculates the figures.
For business books, share receipts or statements. For personal spending, reporting your current cash and answering a few broad questions can be enough; you do not need every receipt. Your AI prepares drafts and a summary for you to approve or ask questions about.
Your records and notes stay in a folder you keep, so another assistant can pick up the work later. Local use needs no IrisBooks account. Optional cloud services add sync between computers, browser access, sharing with an accountant and change history; those require an account. IrisBooks is independently developed and operated. The cloud service is free and invitation-only, provided as is without guaranteed individual support or continued updates.
Assess the capabilities of this session, then follow only the matching setup path below. Tell the user which path you chose and why, where the book files will live, and whether cloud sync is available. Tell them what you are about to do at each step, and get their confirmation before running any install command — these run on their machine.
Use a separate persistent work folder per client. Give that client’s assistant VM or equivalent environment read/write access only to this folder, containing the client’s fiscal-year books. Enforce the boundary through environment permissions; a separate conversation alone is insufficient. Keep a persistent copy outside temporary VM storage.
Before using either setup path, check connected tools and cloud credentials as well as file mounts. A shared host MCP server or firm-wide credential can reach beyond the mounted folder. Keep those outside the client’s AI session unless their access is confined to that client; broader clone/sync or administration can happen separately. Verify the actual boundary before claiming client isolation. Reuse the existing shared book’s files and identity.
Do not infer capabilities from the assistant’s product name or subscription. A desktop agent, a cloud VM, a browser chat, and a mobile session may expose different tools even within the same product. Check your actual tools and permissions; if a capability is unknown, ask the user before relying on it.
| Priority | Path | Required capabilities |
|---|---|---|
| 1 | CLI — Path A | Shell execution, outbound web access to the installer and release downloads (including redirects), permission to download and execute a native binary, and read/write access to a persistent book folder. A web-fetch tool alone is insufficient. |
| 2 | Local MCP — Path B | This session can reach the user’s host MCP server, either already configured or installed through a native .mcpb extension with a parent folder of books. Bookkeeping authoring also requires file access to the selected book. |
| 3 | Return in a capable agent — Path C | If neither CLI nor local MCP is viable, ask the user to reopen this page in Claude Code or an equivalent agent with the required capabilities. |
Recommend Path A (CLI) first. Assess its requirements before suggesting Path B; when both are viable, recommend and proceed with Path A. If downloads, binary execution, filesystem access, or the requested sync flow are blocked, explain the specific blocker and guide the user through Path B instead. For local MCP, verify that this session can actually call the host’s tools; installing an extension on the user’s computer does not prove a cloud VM can reach it. Do not keep retrying a blocked installation or invent a host bridge.
An existing local, synced book is also a Path B use case. The user may
already have iris, a book folder, and sync authorization on their computer,
then want to work in Cowork or an equivalent assistant running in a VM.
The VM may see mounted book files but cannot invoke the host’s iris or its
authorized sync session. Use the host’s local MCP server to validate, report,
and sync that same book. A CLI installed inside the VM is a separate
installation; it does not give access to the host’s sync authorization.
Preserve the working host setup and verify local MCP reachability.
Cloud sync adds an authorization requirement. The default iris api login
flow needs a browser in which the user can sign in and approve, and that
browser must reach the CLI’s localhost callback on the machine running iris.
A browser on the user’s computer cannot necessarily reach a cloud VM’s
localhost. Some VM surfaces, such as OpenAI Dot, block localhost callbacks.
Local bookkeeping still works without browser access or an account.
For a browser/executor that blocks localhost but shares browser downloads with
the shell, the released CLI also supports file-based authorization:
iris api login --handoff-file, then iris api login --complete <downloaded-file-path>.
Use this only when the browser can download the approval file and the executor
can access it; see Path A’s sync instructions. If neither authorization route
works and the user wants sync, move to Path B or C rather than claiming sync
is ready. If they choose local-only use, Path A can proceed without login.
Remote MCP is for mobile / on-the-go access to cloud-linked books. It is an optional companion after local setup and sync, not the main installation target or a replacement for an unavailable CLI/local MCP setup. See the remote-access section below.
iris already installed?Run iris version.
iris update --check --json. When
status is update_available, show the installed/latest versions and
obtain authorization for an update. Invoke the updateCommand argument
array from the report (it targets the executable actually running), then
continue to A3. Do not treat a failed check as “up to date”; local
bookkeeping still works offline.iris update is an unknown command, this is an older binary: read
https://irisbooks.io/dl/latest/version.txt and compare with iris version.
If older, use A2’s installer with authorization. Check for a different
copy on PATH or a registration pointing at the old download location.iris CLIExplain that the CLI is free and provided as is, with no guaranteed individual support, bug fixes or continued updates, before asking to install it.
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.io/install.sh | sh
Windows (PowerShell):
irm https://irisbooks.io/install.ps1 | iex
For an existing installation, stop its IrisBooks MCP server before replacing it on Windows if the executable is locked. Installers stage and verify the new executable before replacing the old one. Downloads use one resolved release version, so a release published during installation cannot mix assets.
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 the environment blocks installation, return to the capability check and assess Path B. There is no per-book bundled binary to look for. If you are in a VM, explain its storage lifetime and how the user will retain their book before creating files there; do not describe a VM folder as their local disk.
Ask the user whether they have an existing IrisBooks book folder.
iris init --name "<Name>" --region <JP|US> "<path>".
The region defaults to JP; the fiscal year starts in January and defaults
to the year containing today — ask when the business’s year starts in
another month (a company whose year starts in April adds
--fiscal-start-month 4) or covers another year. When the region
has an overlay, init pins it in config/book.yaml (overlay: jp@… for
JP). Leave that line alone: it changes only through iris overlay upgrade,
when the user asks. A region without an overlay yet gets the
universal checks only, with no overlay: line.<book> below.After creating or selecting the book, give the user the folder explanation below before continuing to A4.
You can drive the book directly with the CLI from its folder: run
iris validate, iris balance, iris report --help, and iris status as
needed. CLI use does not require MCP support.
If your client supports local MCP and you want its tool integration, 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.
For direct CLI use, run iris status and iris validate in the selected book,
then continue to A6. If you registered MCP, your 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. Continue
over the CLI while tools are unavailable; do not claim MCP is connected.
Call check_update after restarting to verify the MCP server’s running
version and executable path; it may be a different copy from the CLI on PATH.
If the tool is absent, the server is still an older binary: inspect its
registration and rerun onboard from the updated executable. A .mcpb
extension contains its own binary: reinstall the matching bundle through the
client’s extension settings using the same parent folder of books, then
restart and check again. A standalone CLI update does not replace a bundle.
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/, journals/ or assets/.balance / report — trial balance, P&L, balance sheet (machine-readable).sync — push/pull against the cloud (needs iris api login first).jp_teiritsu) — run it rather than
computing those figures yourself. Use the selected book’s available
recipes; community and book-specific overlays can extend this set.Use native filesystem tools for routine file reads, text searches, and draft
edits. iris search provides structured journal filters (also available as
MCP search_journals); CLI iris show traces document references.
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.
Only start this when the user wants sync. For a browser that can reach the
CLI’s localhost callback, run iris api login and let the user sign in and
approve. For a browser/executor with shared downloads but no localhost access:
iris api login --handoff-file
# Open the printed consent URL; the user signs in and approves.
# The browser downloads iris-login.json to a folder the shell can access.
iris api login --complete "<downloaded-file-path>"
iris api whoami
Pass only the downloaded file’s path to the CLI. Do not read, print, or paste
its contents, pending-login files, or session credentials into the conversation.
The approval code expires five minutes after approval; start again if it
expires. Remove the downloaded file after completion. Verify login with
iris api whoami for either flow.
Inspect the selected book’s existing cloud identity before creating anything.
In an unlinked local book folder, iris api books new creates and links a
cloud mirror from its local settings. To connect to an existing cloud book,
use iris api books list and iris api books link <book-id> instead. Then run
iris sync in the book folder and check the result. Linking existing local
and cloud content may produce conflicts; do not overwrite them silently.
Recommend Path A first for a new setup. Use Path B when CLI is not viable in this session, including when a VM assistant needs to operate an existing host book and invoke sync through the host’s authorized local MCP server.
If local MCP is already connected, verify it with check_update and
auth_status, then identify the existing book with list_books in
parent-folder mode or status in single-book mode. Use the same book folder
and cloud identity. For an already-linked book with auth_status: signed_in,
call sync(book=<child-folder-name>) in parent mode or sync in single-book
mode. There is no need to reinstall, log in again, or create/link/clone a
second book. Inspect the tool schemas: single-book tools need no book
argument. Give the VM file access to that same host folder for authoring.
If local MCP still needs to be installed, guide the user through downloading
and installing the .mcpb; do not just mention that a bundle exists. Follow
the steps below, using the existing book’s parent folder when there is one.
Wait for the user to complete the download and installation before checking
for tools. The .mcpb includes its own iris binary; the user does not need
to install the CLI separately or type terminal commands.
.mcpb file onto that computer:
.mcpb, and follow the installation prompts. Labels
vary by client; ask what they see if needed. The client must support native
.mcpb bundles; a remote connector URL field is not this installer.books_dir) as the parent
directory containing book folders, for example ~/IrisBooks with books
at ~/IrisBooks/MyBusiness and ~/IrisBooks/Personal. For an existing book,
select its parent, not the book itself. An empty parent is fine for a new
start. For an accountant, use a client-specific parent such as
~/IrisBooks/ClientA, with only Client A’s fiscal-year books as children.
The bundled server runs iris mcp serve --books-dir <parent>.check_update and list_books. If tools
remain unavailable, explain the missing capability and use Path C. For
bundle updates, have the user reinstall the bundle at the reported
downloadURL, retain the parent setting, restart, and check again.create_book with those settings. The parent itself is never initialized as a book. Pass
book=<child-folder-name> on every book operation; there is no shared
active book. Validate the selected book and read its CLAUDE.md and
LLM-GUIDE.md through file access before the first real task (as in A6).
If file access is unavailable, explain that authoring is blocked and help
the user grant it or use Path C.After creating, selecting, or cloning a book, give the user the folder explanation below. Use the host path returned by the MCP tools, and include the mounted path separately if the assistant sees a different path.
For optional sync, call auth_status first and reuse a verified signed_in
host session. If sign-in is needed, call login, let the user approve in the
host browser, then call auth_status and require signed_in. The callback
belongs to the host MCP server, not the assistant’s VM. If the selected book
is already cloud-linked, call sync(book=...) using that identity. For an
unlinked book, call list_cloud_books and inspect the intended identity: use
create_cloud_book(book=...) for a new mirror of an unlinked local book, or
link_book(book=..., cloud_book_id=...) for an existing cloud book. Then call
sync(book=...) and check the result. To bring down an existing cloud book
instead, call clone_book(book=<new-child-folder>, cloud_book_id=...) into an
absent/empty destination; do not call create_book first.
For region recipes in parent-folder mode, call list_recipes(book=...), then
run_recipe(book=..., recipe=..., params=...) using the returned schema.
Before moving on, briefly tell the user in their language:
raw/. The user asks their AI assistant to record transactions or explain
reports, the assistant
edits the files, and iris validates entries and calculates the figures.
The default is review before posting; follow the book’s chosen policy.
They can resume later by opening this folder with their assistant; local
bookkeeping needs no account.iris sync or MCP sync(book=...). On another
computer, sign in to the same account and clone the existing cloud book
with iris clone or MCP clone_book rather than creating a second book.
Sync before working to pull changes and after working to push them;
creating a local book alone does not enable cross-machine sync. Follow
https://irisbooks.io/manual/en/getting-started/ (Japanese:
https://irisbooks.io/manual/ja/getting-started/) for the second-machine steps.State whether this book is local-only or cloud-linked, and whether a sync actually succeeded. Offer to help enable sync when they want it, and keep local-only use available.
If neither CLI nor local MCP is available for the requested setup, explain which capability is missing and ask the user:
Open Claude Code or an equivalent agent with web access, binary download and execution, and access to a persistent book folder. Return to https://irisbooks.io/start and ask: “Set up IrisBooks for me using this guide.”
If they want sync, include the browser authorization requirements from the capability check. Preserve any existing book and share its location for the next session. Do not claim installation succeeded or send them to remote MCP as the default setup workaround.
Once a book is cloud-linked and synced, the user can connect a supported mobile/web assistant to the remote MCP connector to access it away from their computer. Follow https://irisbooks.io/manual/en/remote-connector/ (Japanese: https://irisbooks.io/manual/ja/remote-connector/). This requires an IrisBooks account and connector authorization; it does not install local tooling or provide direct access to the local book folder. Remote writes are drafts; posting and local file authoring stay in the main bookkeeping workflow.
Use the product explanation at the top, then relate it to the setup you
actually completed. Local iris needs no account or network; the user’s AI
may have its own network requirements. Cloud adds sync, the web app, sharing
and server-side correction/deletion history. Local files alone do not supply
that server history. Explain relevant compliance features without promising
that setup alone establishes compliance with local laws or rules.
Give the actual folder location and local/cloud state as described above. If the user wants cloud services, use the chosen path’s login, create/link and sync steps. Do not claim sync is active until it has succeeded.