# AI (Full) --- source: /docs/ai.md # AI AI can help draft transactions, answer questions, build scripts, and prepare review work. Bkper keeps the source of truth in zero-sum Books: every transaction moves resources from one Account to another, balances are calculated from records, and events preserve review history. ## Where to start - [Fundamentals](https://bkper.com/docs/ai/fundamentals.md): Understand LLMs, hallucinations, context, agents, and why financial numbers need deterministic checks. - [Bkper Agent](https://bkper.com/apps/bookbot.md): Draft transactions and process documents inside Bkper with human review. - [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md): Use the terminal agent with local files, shell commands, scripts, tests, and Bkper CLI context. - [Bkper MCP Server](https://bkper.com/docs/ai/bkper-mcp-server.md): Connect hosted assistants such as ChatGPT or Claude to Bkper through existing permissions. - [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md): Choose the right workspace: local CLI tools when possible, hosted MCP when local tools are unavailable. - [AI Tooling](https://bkper.com/docs/ai/tooling.md): Use Markdown docs, llms.txt, API references, discovery endpoints, and agent skills. - [Coding Agents](https://bkper.com/docs/ai/coding-agents.md): Build Bkper scripts, reports, apps, and integrations with grounded coding agents. - [Agent Security](https://bkper.com/docs/ai/security.md): Limit workspace access, protect credentials, scope permissions, and review mutations. - [OpenAccountants](https://bkper.com/docs/ai/openaccountants.md): Combine Bkper books, cited tax rules, AI-assisted worksheets, and professional review. ## Safety rule Raw AI output is not final for balances, statements, reconciliations, taxes, or filing decisions. Use AI to draft, organize, explain, and build tools. Let Bkper records, deterministic checks, and human review carry the final financial answer. --- source: /docs/ai/bkper-cli-agent.md # Bkper CLI Agent The Bkper CLI includes a built-in terminal AI agent. Use it when you want an agent to work with local files, shell commands, scripts, tests, and Bkper CLI context in the same workspace. This page explains the agent workflow. The canonical install, authentication, and command reference lives at [Bkper CLI](https://bkper.com/apps/bkper-cli.md). ## Use it when - You want an agent to inspect local project files or `AGENTS.md`. - You need shell commands, pipes, scripts, tests, or exported CSVs. - You are building a repeatable report, import, cleanup, or integration. - You want deterministic checks instead of raw AI answers for financial outputs. For hosted assistants without local tool access, use [Bkper MCP Server](https://bkper.com/docs/ai/bkper-mcp-server.md). For the full decision guide, see [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md). ## Quick start 1. **Authenticate the CLI with Bkper** ```bash bkper auth login ``` 2. **Start the terminal agent** ```bash bkper ``` or: ```bash bkper agent ``` 3. **Connect model access** On first launch, type `/login` inside the agent. `bkper auth login` connects the CLI to Bkper. `/login` connects the interactive agent to an AI/model provider. ## Safe workflow Ask the agent to work in small, reviewable steps: 1. Read the relevant files, docs, or Bkper data. 2. Explain the plan before making changes. 3. Show exact commands for any write or batch operation. 4. Wait for your confirmation before mutating Bkper data. 5. Verify numeric results through Bkper APIs, scripts, tests, or reports. ## Starter prompts ```text Explain the account types in this Bkper book and list anything that looks unusual. ``` ```text Find possible duplicate transactions from last month. Do not modify anything; show me the query and reasoning first. ``` ```text Write a script that exports a monthly profit and loss report from Bkper balances. Keep the calculation deterministic and add a simple test fixture. ``` ```text Review unchecked transactions from this month and suggest what needs attention. Do not post, check, or edit transactions. ``` ```text Prepare an exploratory tax worksheet for 2025 from my Bkper data. Use Bkper as the source of truth and mark assumptions explicitly. ``` ## Watch walkthroughs Optional walkthroughs: - [Bkper CLI Agent walkthrough](https://www.youtube.com/watch?v=gFkOZjfEOf8) - [Bkper CLI Agent workflow example](https://www.youtube.com/watch?v=0fSyYdwwR_I) ## Security The agent runs with your local workspace access and the Bkper permissions of the account used by `bkper auth login`. Before using it with real data, read [Agent Security](https://bkper.com/docs/ai/security.md). ## Reference Use [Bkper CLI](https://bkper.com/apps/bkper-cli.md) for canonical installation, authentication, CLI command reference, and current agent behavior. --- source: /docs/ai/bkper-mcp-server.md # Bkper MCP Server Bkper MCP is the hosted Model Context Protocol server for Bkper. It lets ChatGPT, Claude, and other MCP clients work with your Bkper books through your existing Bkper account permissions. This page is a high-level orientation. The canonical setup, endpoint, and current capability reference lives at [Bkper MCP](https://bkper.com/apps/bkper-mcp.md). ## Use it when - You want to ask a hosted assistant about your Bkper books. - You are doing quick, read-heavy exploration. - You need connector-based access without a local terminal setup. - Local files, shell commands, tests, and scripts are not required. The hosted endpoint is: ```text https://mcp.bkper.app/mcp ``` Follow [Bkper MCP](https://bkper.com/apps/bkper-mcp.md) for setup instructions because connector screens and capabilities can change. ## Try asking Good first questions are narrow and reviewable: - “List my books and show which one looks like the operating company.” - “Show the main accounts and groups in this book.” - “Summarize unchecked transactions from last month.” - “Find transactions that may need review before reconciliation.” For any write, give the assistant a standing instruction: ```text Before making any change in Bkper, explain the exact plan and ask for my confirmation. ``` ## Safety model When you connect Bkper MCP: - you authorize access with Bkper OAuth; - your existing Bkper permissions still apply; - Bkper remains the source of truth for books, transactions, groups, accounts, balances, permissions, lock dates, and audit history; - write operations should require an explicit plan and your confirmation before they happen. ## Use CLI instead when MCP is usually not the strongest path for work that needs local artifacts: - scripts and repeatable reports; - shell pipes, `jq`, CSV transformations, or local files; - app development; - tests and deterministic build artifacts; - long multi-turn work that benefits from project context. For those workflows, use local CLI tools whenever possible. See [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md). ## Related pages - [Bkper MCP](https://bkper.com/apps/bkper-mcp.md) — canonical setup and reference. - [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md) — choose the right workspace. - [Agent Security](https://bkper.com/docs/ai/security.md) — protect data, credentials, and permissions. --- source: /docs/ai/cli-vs-mcp.md # CLI vs MCP Use the CLI/local-tool path whenever possible. Use MCP when local tools are not possible or when a hosted assistant is the right workspace. This is not about one agent brand. The same rule applies to Bkper CLI Agent, Claude Code, Codex, Cursor, OpenCode, Pi, OpenClaw, Hermes Agent, and other agents that can operate local tools and files. ## Choose by workspace **Use CLI/local tools** when the work needs files, scripts, tests, shell commands, CSVs, `jq`, project context, or repeatable financial artifacts. **Use MCP/hosted assistants** when you want connector-based access in ChatGPT, Claude, or another hosted client and local tool access is not available or not needed. If both are possible, start with CLI/local tools. ### Durable context Local workspaces preserve files, scripts, fixtures, exports, tests, and intermediate artifacts. An agent can create a report script today, improve it tomorrow, and leave a reproducible trail in your project. A hosted chat can remember a conversation, but it usually does not own the same durable working directory. ### Pipes and deterministic tools CLI output can be filtered, transformed, reviewed, and fed into other deterministic tools: ```bash bkper transaction list -b -q 'on:2026-06' --format json \ | jq '.items[] | {date, description, amount}' ``` That matters in finance. Raw LLM output should not be the final word on balances, statements, reconciliations, or taxes. Local tools make it easier to produce auditable artifacts. ### Agentic capability Local agents can: - read and write project files; - run `bkper` commands; - call APIs through scripts; - run tests and formatters; - iterate on failures; - leave checked-in code or reports behind. Computer-use and “claw” agents such as OpenClaw, Hermes Agent, and similar tools are especially strong with the CLI path because they can operate local tools and files. ## Common choices Prefer **CLI/local tools** for: - building a script, report, or app; - using project files, tests, fixtures, or `AGENTS.md`; - running shell pipes, `jq`, or CSV workflows; - producing deterministic financial artifacts; - drafting or mutating Bkper data when review and confirmation are required. Prefer **MCP** for: - quick questions in ChatGPT or Claude; - read-heavy exploration; - listing books, accounts, groups, transactions, or balances from a hosted assistant; - workflows where the assistant has no local files, shell, or CLI access. Both can be useful for quick book-structure exploration. For mutations, prefer CLI/local tools if possible and always require explicit confirmation. ## MCP in local coding tools Some coding tools can use MCP as an additional connector. That can be useful, but it is not the same as local CLI plus shell plus project context. If your agent can run local commands, prefer the Bkper CLI for Bkper operations and use MCP as a supplement only when it fits the workflow. ## Recommended default 1. If you can use a terminal workspace, install and authenticate the [Bkper CLI](https://bkper.com/apps/bkper-cli.md). 2. Use [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md) or your preferred local coding agent with the Bkper CLI skill/plugin. 3. Use [Bkper MCP Server](https://bkper.com/docs/ai/bkper-mcp-server.md) when you need hosted assistant access or cannot use local tools. 4. For any mutation, require an explicit plan and confirmation before data changes. ## Related pages - [AI Fundamentals for Finance](https://bkper.com/docs/ai/fundamentals.md) - [AI Tooling](https://bkper.com/docs/ai/tooling.md) - [Agent Security](https://bkper.com/docs/ai/security.md) --- source: /docs/ai/coding-agents.md # Coding Agents AI coding agents are the fastest way to go from idea to working Bkper integration. They can scaffold projects, write SDK code, debug issues, and iterate with you in real time — as long as they have the right context about the platform. Use whichever agent harness you're most comfortable with. They all work well. But we have a recommended starting point. > **Tip: New to AI?** > If you're new to how LLMs, context, and agents work, read [AI Fundamentals](https://bkper.com/docs/ai/fundamentals.md) first. It covers the mental model you need before building with AI. > **Caution: Security** > Coding agents run with your permissions. Before using them with real Bkper data, read [Agent Security](https://bkper.com/docs/ai/security.md) to understand container isolation, credential protection, and permission scoping. ## Bkper CLI Agent (recommended) The Bkper CLI ships with a built-in coding agent. It's powered by [Pi Agent](https://pi.dev) with a custom system prompt that gives it deep knowledge of Bkper — core concepts, the SDK, CLI commands, and the accounting model. It's what the Bkper team uses every day, and the choice of Pi as the engine was deliberate. #### Why Pi We spent over a year working heavily with coding agents — Claude Code, Cursor, OpenCode, Codex — before settling on Pi as the foundation for Bkper CLI Agent. The reasoning comes down to three things: - **Distribution** — One install gets you everything. The Bkper CLI bundles the Pi agent runtime and all Bkper domain context, so `bkper agent` works the moment the CLI is installed. You don't need a separate agent harness, a skill download, or manual context setup. One package, one command, and the from-to model, SDK types, and CLI references are already loaded. - **Philosophy** — Pi is built around a minimal, well-done core that you extend through TypeScript extensions, skills, and packages instead of fighting an opinionated black box. That mirrors how we think about Bkper: a simple, rigorous accounting engine with powerful hooks for apps, bots, and automations. Embedding Bkper's domain into Pi felt natural because both systems share the same shape — get the core right, then get out of the way. - **Model freedom** — 15+ providers (Anthropic, OpenAI, Google, and more), including low-cost hosts for open-weight models. Use Claude or GPT when the task demands peak capability, and switch to affordable APIs serving Kimi, Qwen, or DeepSeek when it doesn't. Run models locally too if you prefer. The freedom to choose the best model for the task also means the freedom to choose the most cost-effective option. AI assistance should be available to everyone, not just those with a premium API subscription. > **Note: We're still early** > Nobody knows what the ideal AI coding workflow looks like yet. Pi's bet — give developers a minimal, hackable foundation instead of an opinionated black box — matches how we think about developer tools at Bkper. [Lucas Meijer's talk](https://youtu.be/fdbXNWkpPMY?t=796) captures this mindset well. > **Tip: Further watching** > - [Lucas Meijer on Pi's minimal, hackable design philosophy](https://www.youtube.com/watch?v=fdbXNWkpPMY) > - [Pi Agent overview and capabilities](https://www.youtube.com/watch?v=Dli5slNaJu0) > - [Pi architecture explained: agent loop, tools, TUI, and more](https://www.youtube.com/watch?v=gTeujlv8qK0) — technical deep dive > - [Pi Agent in action](https://youtu.be/OMFIPv8a4qA?t=8) > ::: > > Make sure the [CLI is installed](https://bkper.com/apps/bkper-cli.md) and authenticated, then start the agent: > > ```bash > bkper agent > ``` > > [Image: Bkper CLI Agent terminal interface showing the Bkper ASCII art header, command shortcuts, context, and an active input prompt] > > :::tip[Windows users] > Run the agent inside [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) for the best experience. Terminal agents rely on Linux tooling that works more reliably under WSL than native Windows. Clone your project into the WSL filesystem (e.g. `~/code/`) for best performance — Windows files are also accessible via `/mnt/c/`. #### Connect a model provider The agent needs access to a language model. On first launch, type `/login` and select a provider. We recommend [OpenCode Go](https://opencode.ai/go) for low-cost open-weight models. For frontier model access, use a [Codex subscription](https://developers.openai.com/codex/pricing) — one of the most affordable ways to use frontier models in coding agents. Once logged in, you're in an interactive session. The agent can read your project files, run CLI commands, write code, and iterate with you — all with Bkper context already loaded. #### Start asking questions Just talk to it. Good starting prompts: - `What are the main account types in Bkper?` - `How do I query transactions using the CLI?` - `What files are in this project?` - `Help me create a script that lists all accounts in my book` The agent reads your project's `AGENTS.md` and nearby files automatically, so it already has project-specific context. Since Bkper CLI Agent wraps [Pi Agent](https://pi.dev), you can pass any Pi flag through — `--model`, `--continue`, `@file` references, and so on. ## Other coding agents Any coding agent can build effectively with Bkper when given the right context. Here are the ones we've used and recommend. The same approach also applies to general-purpose personal agents such as OpenClaw and Hermes Agent when they can run local tools. | Agent | Type | Models | What it is | | ----------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [Pi Agent](https://pi.dev) | Terminal | 15+ providers — Anthropic, OpenAI, Google, and more | Minimal, extensible harness — the engine behind Bkper CLI Agent | | [Claude Code](https://claude.com/product/claude-code) | Terminal, Desktop, IDE | Claude models | Anthropic's full-featured agent across all surfaces | | [OpenCode](https://opencode.ai) | Terminal, Desktop, IDE | 75+ providers — free models included, works with Copilot and ChatGPT subscriptions | Open-source agent with the largest provider ecosystem | | [Codex](https://openai.com/codex/) | Terminal, Desktop, IDE | OpenAI — works with your ChatGPT plan | OpenAI's open-source coding agent | | **[AMP](https://ampcode.com)** | Terminal | Multiple providers — works with Claude, OpenAI, and more | Open-source coding agent built for AI-native development workflows | | [Cursor](https://cursor.com) | Terminal, Desktop, IDE | Multiple providers built in | AI-native code editor with a terminal agent | Each tool has its own way of loading project context. The next section explains how to provide Bkper knowledge to any of them. ## Giving your agent context Bkper CLI Agent has context built in. For other agents, you need to provide it. ### Install the Bkper CLI skill For external agents that support the [Agent Skills standard](https://agentskills.io) and can run local shell commands, install the Bkper CLI skill: ```bash npx skills add bkper/bkper-cli --skill bkper-cli ``` This is the portable version of what we learn from the first-party Bkper CLI Agent. It gives other harnesses Bkper's from-to accounting model, CLI references, SDK pointers, and safety guardrails for operating the local `bkper` CLI. [Source on GitHub](https://github.com/bkper/bkper-cli/tree/main/skill). Install and authenticate the CLI first when the agent needs live Bkper access: ```bash npm i -g bkper bkper auth login ``` ### Direct Markdown access If your agent doesn't support skills, or if you only need general Bkper knowledge without local CLI operations, load context manually. Every page on bkper.com is available as clean Markdown — append `.md` to any URL: ```text https://bkper.com/docs/core-concepts.md https://bkper.com/docs/api/bkper-js.md https://bkper.com/docs/build.md ``` This strips navigation chrome and reduces token usage. See [AI Tooling](https://bkper.com/docs/ai/tooling.md) for all access methods. Three URLs cover most Bkper development needs: | URL | What it covers | | ------------------------------------------------------------------- | --------------------------------------------------------------- | | [`/platform/agents.md`](https://bkper.com/platform/agents.md) | Technical instincts, quality standards, domain sensibilities | | [`/docs/core-concepts.md`](https://bkper.com/docs/core-concepts.md) | The from-to model, account types, transactions, groups, queries | | [`/docs/api/bkper-js.md`](https://bkper.com/docs/api/bkper-js.md) | Full bkper-js SDK reference with TypeScript types | Use whichever combination your project needs. ### Project-level context files For project-specific knowledge — which book you're working with, what accounts matter, what tags to use — add it to your agent's context file (`AGENTS.md`, `CLAUDE.md`, or equivalent): ```markdown ## Project context - Book ID: abc123-def456 - Key accounts: Checking, Sales, Accounts Receivable - Common tags: #invoice, #payment, #reconciled ## Rules - All automated transactions must be created as drafts - Use the #sync tag on all imported transactions ``` This gives the agent project-specific knowledge that no published doc can provide. ## Next steps - [Your First App](https://bkper.com/docs/build/apps/first-app.md) — build and deploy a full Bkper app (a great task to pair with an AI agent) - [CLI Scripting & Piping](https://bkper.com/docs/build/scripts/cli-pipelines.md) — automate data workflows with CLI pipes - [Apps Overview](https://bkper.com/docs/build/apps/overview.md) — understand the Bkper Platform architecture --- source: /docs/ai/fundamentals.md # AI Fundamentals for Finance Most people meet AI through a chat box. You type a question, you get an answer, and it feels like a calculator that talks. It is not. Working with AI in accounting — where numbers must be correct, not approximately correct — requires a different mental model. This page covers the minimum you need: how Large Language Models behave, what to feed them, how to ask, how agents work, and the one rule that keeps AI usable for finance. ## LLM Nature A Large Language Model does not look up answers. It predicts the most likely next word, piece by piece, with randomness baked in. Different models trade off speed for depth, but all share this nature. The consequence is unintuitive: **the same prompt can produce different answers**. Ask an LLM to compute a tax three times and you may get three slightly different numbers. The fourth try might be wrong by a wider margin. LLMs are **probabilistic**, not deterministic. Treat their direct output as a draft, never as a verdict. ## Hallucinations When an LLM does not know something, it does not stop. It guesses — fluently, confidently, and often wrongly. It will invent account names that don't exist, cite tax rules that were never written, and reference invoices it has never seen. This is called **hallucination**, and it is not a bug to be patched away. It is a direct consequence of how the model works.

Video: “Never Trust An LLM” by Matt Pocock.

The lesson is simple: **never trust raw LLM output for facts**. Verify, ground, or — better — route the work through something deterministic. ## Context Hallucinations get worse when the model has nothing to ground itself on. That is where context comes in. An LLM only knows what is in its **context window** right now: your current prompt, the files you attached, the recent conversation. It does not know your books. It does not remember last week. Each session starts blank. You build context by handing it relevant pieces — a chart of accounts, a transaction list, a policy document, a project's `AGENTS.md`, an installed skill. Persistent context, such as skills or project files, saves you from pasting the same information every time. But context has a sweet spot. Too little, and the model invents. Too much, and it loses focus, mixes unrelated pieces, and slows down. **The key is curation** — give the model exactly what it needs to answer the question in front of it, nothing more. The curve never touches zero because better context reduces hallucination risk; it does not make the model deterministic. ## Intent Intent means telling AI what done looks like, not listing every step. A useful prompt names four things: **outcome**, **reason**, **source of truth**, and **success criteria**. #### Old habit: step-by-step > “Open my book, filter transactions tagged `#sales` for Jan–Mar, sum the VAT column, convert to EUR, give me the total.” You are scripting the work. The model can still misread a step, skip one, or invent around it. #### Better habit: intent > “I need the VAT I owe for Q1 2025, in EUR, ready to file. Use my Bkper book as the source of truth.” You describe the outcome. The agent can decide which transactions to pull, which tag to trust, which math to run, and whether to answer directly or write a small script. #### Success criteria Pair intent with a concrete check: an expected total or range, a report shape that matches last quarter's, a reconciliation that should come out to zero, or a specific account whose closing balance you know. Without that, the model has no way to know when it is done — and neither do you. ## Agents An **agent** is an LLM running in a loop with tools. At each step the model proposes an action, runs a tool — a CLI command, a script, an API call — and observes the result. That observation feeds the next step, which may be progress, a correction, a retry, or a different approach. The loop keeps turning until the success criteria are met. This is the shape behind the [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md) and every other AI assistant that does real work. The success criteria is what closes the loop — without it, a probabilistic engine running freely produces drift, not progress. And a loop is only as trustworthy as the tools inside it. ## AI in Accounting AI fundamentals apply across finance. The accounting layer is where they get strict — because accounting numbers don't have a tolerance band. Accounting cannot be 99% right. A balance sheet that is mostly correct is wrong. A tax filing that is approximately accurate is a problem. And no technique — better prompts, richer context, smarter agents — makes an LLM's output guaranteed correct. Errors will happen, and inside an agent loop they compound silently between checks. So the rule is not *make the AI correct*. Nothing makes the AI correct. The rule is: > **Never let unverified LLM output be the final word on a number.** The practical question is how to keep verification cheap. That is what code is for. When an LLM writes a script that computes the answer, you stop verifying outputs and start verifying the script. You read it once, test it, and trust it as long as it doesn't change. From then on the same inputs give the same outputs, auditable line by line. Verification becomes a one-time cost instead of a per-result cost. That shifts the rule into a practical split: - **Deterministic work** — tax calculations, reports, reconciliations, financial statements, balance computations — has a single correct answer that must be reproducible. Have the LLM write code or call a deterministic tool, then verify the code, not each output. The work becomes repeatable, auditable, and reusable. - **Non-deterministic work** — spotting suspicious transactions, surfacing business insights, bootstrapping a chart of accounts, summarizing a period — has no single correct answer. Direct LLM output is acceptable here, but only as a draft for a human to review and decide on. In both cases the human stays in the loop. AI doesn't remove the reviewer; it changes what arrives for review. With code carrying the deterministic load, the human is checking artifacts a human can actually check — a script, a report engine, an app — instead of re-checking every number the model emits. ## What's next - [AI Tooling](https://bkper.com/docs/ai/tooling.md) — get Bkper docs and context into AI tools. - [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md) — choose the right workspace for the job. - [Coding Agents](https://bkper.com/docs/ai/coding-agents.md) — build Bkper integrations with grounded coding agents. --- source: /docs/ai/openaccountants.md # OpenAccountants Use this path when you need tax or accounting review without trusting raw AI answers. Bkper provides the source-of-truth books. OpenAccountants provides cited rule grounding and professional handoff. ```text Clean Bkper books → AI-assisted worksheet → OpenAccountants cited rules → accountant review ``` ## The problem Raw AI tax answers are unsafe. Models may: - recall stale tax rules from memory; - blend rules across jurisdictions; - hallucinate citations; - miss filing context; - produce confident but unverifiable numbers. That is not good enough for tax, accounting compliance, or decisions with financial consequences. ## What Bkper contributes Bkper provides the financial source of truth: - zero-sum books where every transaction moves resources from one Account to another; - accounts, groups, properties, hashtags, and files that structure the business reality; - balances calculated from transactions, not guessed by an LLM; - permissions and audit events that show who or what changed data; - drafts, unchecked, and checked states that keep humans in the review loop. AI can draft, explain, and organize, but Bkper keeps the records and balances grounded. ## What OpenAccountants contributes OpenAccountants provides the rule and professional-review layer: - open tax-rule bundles by jurisdiction; - cited rules rather than uncited model memory; - review status and accountant-verified sections; - a verified accountant network for professional handoff. For tax matters, this matters because the final answer depends on jurisdiction, period, facts, rule interpretation, and professional judgment. ## How the workflow fits together A practical workflow looks like this: 1. Keep transactions and supporting files in Bkper. 2. Use Bkper balances, queries, and reports as the source of truth. 3. Let AI draft a worksheet or issue list from the Bkper data. 4. Ground tax-rule questions with OpenAccountants cited rules for the relevant jurisdiction. 5. Send the structured worksheet and supporting context for accountant review when stakes require it. The AI drafts and organizes. Rules provide grounding. A credentialed human owns review and signoff when the decision matters. ## What to prepare from Bkper Before handoff, prepare the smallest useful package: - book and period being reviewed; - relevant reports or balance queries; - supporting files, receipts, or invoices when needed; - assumptions and open questions; - any transactions that are drafts, unchecked, unusual, or disputed. Do not send private book data, transaction details, files, tax IDs, or sensitive personal information to third-party tools unless that sharing is explicitly intended and approved. ## Professional handoff OpenAccountants can route users toward its verified network when professional help is needed. Bkper does not endorse, employ, or independently vet specific accountants. Treat the accountant relationship as a professional engagement between you and the professional or network you choose. ## For accountants The network-building side is important. AI-assisted tax and accounting workflows need professionals who can verify rules, review worksheets, and own judgment where rules meet facts. Accountants can help by: - contributing or verifying tax-rule sections for jurisdictions they know; - building a public contribution record; - reviewing AI-generated worksheets instead of rebuilding everything from scratch; - helping clients turn clean Bkper records into reviewable workpapers. Bkper is working closely with OpenAccountants founders and helping the network succeed where possible, especially where Bkper data can make handoff cleaner and review more efficient. ## Related pages - [AI Fundamentals for Finance](https://bkper.com/docs/ai/fundamentals.md) — why raw LLM output is not final for numbers. - [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md) — choose the right AI workspace. - [Agent Security](https://bkper.com/docs/ai/security.md) — protect private book data and third-party sharing boundaries. --- source: /docs/ai/security.md # Agent Security AI coding agents are powerful but run with your permissions. A misconfigured agent can read credentials, overwrite files, or modify live financial data. Three layers of protection keep your Bkper development safe: [Image: Three layers of agent security: sandbox isolation restricts what the agent can reach, credential protection controls how the agent authenticates, and permission scoping limits what the agent can do in Bkper] ## Sandbox isolation The most effective way to limit an agent is to run it inside a sandbox — a container, micro-VM, or OS-level boundary that restricts what it can reach. [Image: Sandbox isolation: the agent can only access project files, CLI, and SDK inside the sandbox boundary, while credentials, SSH keys, and other sensitive files on the host machine remain unreachable] Most agents support a "yolo" or auto-approve mode that skips permission prompts. The per-command approval model sounds safe but creates friction that kills productivity — agents frequently need to run builds, tests, and CLI commands. Pi Agent (and therefore Bkper CLI Agent) runs in yolo mode by default. Running in a sandbox makes this safe: **full autonomy inside a restricted boundary**. ### Built-in sandboxing Some agents sandbox themselves without a container. [Claude Code](https://code.claude.com/docs/en/sandboxing) and [Codex](https://developers.openai.com/codex/concepts/sandboxing) both use OS-level primitives (Seatbelt on macOS, bubblewrap on Linux) to enforce filesystem and network isolation. If you use either, enable their sandbox mode before working with real data. ### Container-based sandboxing For agents without built-in sandboxing — including Pi Agent and Bkper CLI Agent — use a container. We use Docker with [DevContainers](https://containers.dev) and [DevPod](https://devpod.sh) to get reproducible, isolated environments that work the same way locally and in the cloud. Claude Code also publishes a [reference devcontainer](https://code.claude.com/docs/en/devcontainer) designed for autonomous operation with network allowlisting. Other sandbox tools worth knowing about: - [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) — microVM-based sandboxes built for coding agents, with host-side credential injection - [Gondolin](https://earendil-works.github.io/gondolin/) — lightweight micro-VMs with programmable network egress and secret injection - [Podman](https://podman.io) — rootless, daemonless Docker alternative ## Credential protection Even inside a sandbox, the agent can access any credentials present in that environment. The Bkper CLI stores OAuth credentials (including a refresh token) at `~/.config/bkper/.bkper-credentials.json`. If the agent can read that file, it can make API calls as you. ### Host-side credential injection The most secure option. Your credentials never enter the sandbox — an HTTP proxy on the host intercepts outbound API requests and injects authentication headers before forwarding them. [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/security/credentials/) and [Gondolin](https://earendil-works.github.io/gondolin/) implement this pattern. This works well with the Bkper CLI because only `bkper auth login` starts an interactive browser login. Regular CLI commands can proceed without local credentials and let the proxy add authentication. ### Login inside the sandbox, then logout cleanly This is the simplest practical workflow for many teams. Authenticate inside the sandbox with a secondary low-permission account: ```bash bkper auth login ``` When you are done, revoke the refresh token and remove the local credentials: ```bash bkper auth logout ``` `bkper auth logout` does both: - revokes the stored refresh token remotely when possible - clears local credentials from disk If remote revocation fails, the CLI still clears local credentials and warns that remote cleanup may need manual follow-up. ## Permission scoping The Bkper CLI authenticates as the user who ran `bkper auth login`. If that user is the book owner, the agent has owner-level access — it can delete accounts, change sharing settings, and modify lock dates. **Use a secondary account with limited permissions instead.** Log into the CLI with a different Google account (for example, a personal Gmail), then share the target book with that account at the appropriate level: | Permission | What the agent can do | Good for | | ----------------- | ----------------------------------------------------- | ---------------------------------------- | | **View Only** | Read accounts, transactions, and balances | Read-only scripts, reporting, analysis | | **Record Only** | Create and delete drafts | Automated data entry with human review | | **Record & View** | Record drafts, post transactions, view data | Most development and testing workflows | | **Editor** | Full data management (accounts, groups, transactions) | Building apps that manage book structure | Avoid granting **Owner** permission to the agent's account. Owner access allows sharing changes, closing-date modifications, and other irreversible operations that should remain under direct human control. For the full permissions matrix, see [Book Sharing — Permissions](https://bkper.com/docs/guides/using-bkper/book-sharing.md#permissions). ### Combining layers A typical secure setup: 1. **Sandbox** — agent runs inside a DevContainer, Docker Sandbox, or micro-VM with only the project directory mounted 2. **Credentials** — either injected from the host, or authenticated inside the sandbox and explicitly revoked with `bkper auth logout` when work is done 3. **Permissions** — CLI authenticated as a secondary account with Record & View access No single layer is bulletproof, but together they limit exposure to a narrow, time-bound, permission-scoped window. --- source: /docs/ai/tooling.md # AI Tooling Every page on bkper.com is available as clean Markdown. Navigation chrome — sidebar, header, footer — is stripped, reducing token usage for AI tools. ## Formats Three ways to get docs into your AI. Pick the one that matches your workflow. ### `llms.txt` — explore A structured index of every article with descriptions. Start here when you want your AI to browse and pick what to read. - [`/llms.txt`](https://bkper.com/llms.txt) — all site content - [`/docs/llms.txt`](https://bkper.com/docs/llms.txt) — all docs - [`/docs/ai/llms.txt`](https://bkper.com/docs/ai/llms.txt) — AI docs - [`/docs/guides/llms.txt`](https://bkper.com/docs/guides/llms.txt) — user-facing guides - [`/docs/build/llms.txt`](https://bkper.com/docs/build/llms.txt) — developer docs - [`/docs/api/llms.txt`](https://bkper.com/docs/api/llms.txt) — API libraries at a glance ### `llms-full.txt` — deep dive The complete text of every article in a scope. No links to chase, no extra requests. Use this when you need comprehensive context on a specific topic. - [`/llms-full.txt`](https://bkper.com/llms-full.txt) — all site content - [`/docs/llms-full.txt`](https://bkper.com/docs/llms-full.txt) — all docs - [`/docs/ai/llms-full.txt`](https://bkper.com/docs/ai/llms-full.txt) — all AI docs - [`/docs/build/apps/llms-full.txt`](https://bkper.com/docs/build/apps/llms-full.txt) — all app docs - [`/docs/build/scripts/llms-full.txt`](https://bkper.com/docs/build/scripts/llms-full.txt) — all script docs ### `.md` — single page Any individual page as Markdown. Use this when you already know the exact page you need. Append `.md` to the URL: ```text https://bkper.com/about.md https://bkper.com/docs/core-concepts.md https://bkper.com/docs/ai/cli-vs-mcp.md ``` ```sh curl https://bkper.com/docs/core-concepts.md ``` Or request it via the `Accept` header — no URL modification needed: ```sh curl https://bkper.com/docs/core-concepts \ -H "Accept: text/markdown" ``` The response includes an `x-markdown-tokens` header with the estimated token count, which agents can use to plan context window usage: ```text HTTP/2 200 content-type: text/markdown; charset=utf-8 vary: Accept x-markdown-tokens: 1850 ``` Every documentation page also has a **Page Options** dropdown in the right sidebar: ![Page Options dropdown showing copy, view, and AI actions](https://bkper.com/docs/_astro/page-options.QGgo36WO.png) Copy the page as Markdown, open it directly in [Claude](https://claude.ai) or [ChatGPT](https://chatgpt.com), or grab a ready-made prompt for your AI tool of choice. ## API references API reference endpoints compile the library overview and full spec into a single compact document optimized for agent workflows: - [`/docs/api/rest.md`](https://bkper.com/docs/api/rest.md) — endpoints, parameters, and data models - [`/docs/api/bkper-js.md`](https://bkper.com/docs/api/bkper-js.md) — bkper-js README + TypeScript definitions - [`/docs/api/bkper-gs.md`](https://bkper.com/docs/api/bkper-gs.md) — bkper-gs README + TypeScript definitions - [`/docs/api/bkper-api-types.md`](https://bkper.com/docs/api/bkper-api-types.md) — shared TypeScript type definitions - [`/docs/api/bkper-web-auth.md`](https://bkper.com/docs/api/bkper-web-auth.md) — OAuth browser SDK Compiled Markdown vs raw source: | Library | Raw tokens | `.md` tokens | Reduction | | --- | ---: | ---: | ---: | | REST API | ~38K | ~9K | 4× | | bkper-js | ~32K | ~18K | 1.8× | | bkper-gs | ~22K | ~12K | 1.9× | | bkper-api-types | ~12K | ~5K | 2.4× | | bkper-web-auth | ~2K | ~2K | ~1× | ## Agent skills and plugins For coding agents that support the [Agent Skills standard](https://agentskills.io) and can run local shell commands, install the Bkper CLI skill: ```bash npx skills add bkper/bkper-cli --skill bkper-cli ``` The skill is a portable companion for external agents such as Claude Code, Codex, OpenCode, OpenClaw, Hermes Agent, Cursor, and similar tools. It is generated from the Bkper CLI agent configuration and gives other harnesses Bkper's from-to accounting model, CLI references, SDK pointers, and safety guardrails for operating the local `bkper` CLI. Install and authenticate the CLI first when the agent needs live Bkper access: ```bash npm i -g bkper bkper auth login ``` For the built-in terminal agent, see [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md). For hosted connector access without local tools, see [Bkper MCP Server](https://bkper.com/docs/ai/bkper-mcp-server.md). For coding workflows, see [Coding Agents](https://bkper.com/docs/ai/coding-agents.md). [Source on GitHub](https://github.com/bkper/bkper-cli/tree/main/skill).