Bots

A bot is a scheduled agent run on one collection. You write a charter, the standing instruction the bot follows, and pick how often it runs. Each run is an ordinary agent run on the provider you choose, working on its own without you.

What a bot can do

• It writes only to its own collection and that collection's subcollections. It can't rename or delete collections or change your Home pins.
• It reads its own collection, plus any other collections you list in its settings, or the whole vault if you choose that.
• It can't run on or read an encrypted collection.
• It uses the same vault operations as the agent panel, plus web access and the linked folders attached to its collection. It can't create other bots, open things on your screen, use your drafts, or see your conversations.

Setting one up

Open a collection, choose Bot… from its menu, and write the charter. You can also ask the agent to create a bot; it uses the create_bot operation and opens the same dialog.

A new bot is off. It runs only after you turn on Run on this machine in its dialog. That setting is stored on this Mac, so a vault synced to another computer doesn't start the bot there. The charter and schedule are saved in .intabula/bots.json and travel with the vault.

The schedule is counted from the last run, in minutes, hours, or days; the default is once a day. You can also set a time limit and a maximum number of turns per run. By default each run starts a fresh conversation, so the collection itself is what the bot remembers between runs.

When bots run

One bot runs at a time. If you're using the agent panel, a due run waits for it, and a message you send in the panel interrupts a run in progress; the bot tries again on its next check.

Run history

The Bots page in the sidebar lists your bots and their past runs. Opening a run shows every change it made, each as a diff, and the transcript of what the bot did. Changes also appear in the activity feed like any other agent write. A short run log is kept in .intabula/bot-log.json in the vault; the full run details stay on the Mac that ran the bot.

Writing a good charter

The charter is the bot's entire instruction. The bot starts each run with nothing else, so a vague charter gives vague or inconsistent results. Write it as a brief to someone who has never seen the collection: what to check, which fields to fill or change, where to look, and what a finished run looks like.

A charter like "keep my job list up to date" leaves the bot to guess. Compare this one, for a jobs collection with status, url, and checked fields:

For each record in jobs with status "open":
1. Fetch the page in its url field.
2. If the posting is gone or says the role is filled,
   set status to "closed" and add one line to the body
   saying why, with today's date.
3. Otherwise set checked to today's date.
Don't create or delete records. Don't change any other fields.
If a page fails to load, leave the record as it is.

Start with a narrow charter, read the first few runs in the run history, and tighten the wording where the bot did something you didn't intend.