Connecting an agent

Three ways in

Telegram. Message the Countbean bot and it works on your book. Nothing to install, no key to paste, no terminal. This is the path the credits pay for, because the inference is ours.

The Claude plugin. Install it, approve a short code in your browser, pick the book. Uses your Claude subscription, so it spends none of our credits.

Any MCP client. Cursor, Windsurf, Zed, or your own — the same server the plugin talks to.

Linking Telegram to your book

There is one shared bot for everybody, so a message has to prove which book it belongs to before it can reach one:

1. Open your book’s page, signed in, and start a Telegram link. You get a short code.
2. Send that code to the bot.
3. The bot is now bound to that book.

One account, one book. Linking again replaces the previous binding, so “which book am I talking to” always has exactly one answer.

The reason for the browser step is worth stating plainly. A Telegram account id is not a credential — it is an integer anyone can read off their own account, and the bot is public. So the proof has to be produced by a signed-in human in a browser; a message on its own can never create a link.

What you can send it

Text, obviously. Also:

• A photo of a receipt, up to 8 MB — every phone camera. It rides to the model as image data, and Telegram’s largest size is used because it costs the same either way: a 3024×4032 phone photo and a 900×1200 downscale were measured at identical prompt tokens.
• A statement file — csv, ofx, qfx, qif, txt, json — up to 512 KB, which is thousands of rows. Anything else is refused in words rather than quietly fetched, and both limits are checked against the bytes that actually arrive rather than the size Telegram claims.

⚠️ The two limits differ by a lot, and the reason is cost rather than capacity. A photo’s size barely reaches the bill — the model normalises it to about a thousand tokens whatever you send. A statement’s bytes are the bill, so a large one is both expensive and, past a point, larger than the model can read at all. If yours is refused, export a shorter date range: three complete months is what the product needs to tell you anything.

A statement is not read by the model. The bytes go to a parser, which returns the column mapping it used along with the transactions it found — so the same file gives the same answer every time, and the bot tells you which column it read as the amount. The model’s job is to categorise what the parser found and to ask about anything it flagged.

Nothing is written to your book until you agree to it.

Commands that cost nothing

None of these reaches a model, so none of them spends a credit. They keep working when your balance is empty — being out of credits does not mean being locked out of your own books.

/balances	what you have right now, grouped and totalled per currency
/report	your book as a spreadsheet, plus your net worth and where the money went
/status	which book this chat is on, and how many messages you have left
/init	set up your accounts and opening balances
/ingest	what to send, and how much of it
/help	the list, with buttons
/disconnect	detach this chat. Your book is untouched

⚠️ /balances and /report do wake your book’s machine, because they read the ledger. They cost no credits; they are not instant. If the book has been idle you may be told it is waking — ask again in a few seconds.

/help answers before you have connected anything, so you can find out what the bot is first.

Tapping instead of typing

/help and the welcome come with buttons for the free commands, so you do not have to learn the list. A tapped button runs exactly what the typed command would.

⚠️ There is no button for /disconnect. It is one tap from detaching your chat, and that is not a thing to put next to Balances.

What runs where

Your agent runs inside your own book’s machine — one per book, not a shared service, on the machine the book already had. It reaches a model through a metered endpoint we host, which is what turns a turn of conversation into credits rather than an unbounded bill.

Telegram itself is answered by the control plane, not by your book: book machines have no public address, so a webhook could not reach one.

Which to use

If you already live in Claude, the plugin is better — your model, your context, your cost, nothing metered. Telegram exists because the plugin’s install path (a marketplace plugin, python3, a virtualenv, a pasted key) is where people who are not developers stop.

Credits, and the free way round them

Free credits arrive once your email address is verified, whichever way you proved it. If the balance runs out, the bot says so plainly rather than reporting a failure that sounds like an outage — and it names the free route, because there is one: only the chat is metered. The Claude plugin runs on your own model subscription and costs you nothing here.

What there is not

• No WhatsApp. Telegram only.
• No group chats. One account, one book, direct messages.
• The pricing of it is not settled (#253). Metering is live and every turn is measured; what each plan includes is still an open decision, and /pricing says only what can actually be charged today.

What Pip is doing

The agent has four states, and they are states the system really has. Pip reports them; it never claims anything.