---
version: 46
---
# AIObox guide

How an AI acts in AIObox windows: through AkiMCP ops, or a native command this guide names; no scripts.

## House rules

- Never promise a later action ("I'll resend"): what did not happen this turn is reported as not done (step 5).
- Drafts and notes: `/tmp` or your task's own folder. Never write into `~/.aki/aiobox/` (the app's) or `~/.aki/` itself.

## What a window knows

- Itself: `op=whoami`: handle, chatId, `workspace`, `usage` (`session`, `weekly` %, `readAt`).
- `usage` or `workspace` `null` = not known yet; `usageWhy` says why.
- Where to go: `op=state` `workspaces` (per profileId, each workspace's `label`, `status`, `session`, `weekly`).

## Every chat

1. Find yourself: `aki__aiobox op=whoami quote=<20+ chars verbatim from the user's latest message>`. Keep its handle (`P#·W#`, never reused) and chatId (the chat open now; for `from`).
2. `op=state` lists every window, each provider's macros and chat cutoffs (`chatPauses`).
3. Name a window by its handle; add `expect=<chatId>` when it must still hold that chat.
4. New chat: `op=new_chat window=<handle>` (same tab; refused while it answers, holds a draft, or is yours); its chatId exists only after the first `op=send`. Another window: `op=new_window`.
5. Message a chat: `aki__aiobox_write op=send window=<its handle> from=<your chatId>`, now, even mid-answer (`live`/`queued`); only `blocked` (Gemini, Muse), `loading` or a draft: `op=send wait=20`. Muse has no custom MCP: a Muse window is only messaged, never given a role or Connect AkiMCP. Arrived only when `op=read last=2` shows it (no `failed:true`). Sent close together, messages may arrive as one. A refused one AIObox keeps sending again (about 30 min): do not resend, `op=read` it later. Never touch a draft in its box or target your own chat. Tell the user only once it reached someone (who, how many); else "not sent: <target> <reason>".
6. Before reading an answer: `op=wait_idle`, then `op=read`.
7. Macros: `op=run_macro macro=<id from macros>`. Panel reports, by `aki__devtools_eval` (rule 8): `akipanel.surfaceAct('<surface id>','<button id|label>', <row label|index>?)` presses, `akipanel.surfaceInput('<id>','<text>')` fills, `akipanel.surfaces` lists them. In a Notion tab: `akipanel.live.notion.readiness()`; act on `view.next`, not `state`: ready or retry → `op=run_macro macro=connect-akimcp` (no option); dom → `option=dom`; null → nothing to press, tell the user `view.text`.
8. Any tab of any site, by its handle: `op=read`, `op=text selector=<css>`. Beyond the ops: `aki__devtools_eval`, `aki__devtools_screenshot` with the tab's `port` and `targetId` (`op=windows`); never to send a message. Never `chrome_launch` or a CDP close on an AIObox profile.
9. An `ops` op missing from your schema = cached older AkiMCP: `op=run_macro macro=connect-akimcp` on your window, then a new chat.

## Handing work to a new window

A new window is for a subtask, never for your own role out of quota (next section).

1. Pick profile and provider: another account, fewest windows, then most usage left (Notion section).
2. `op=new_window` from a window of that profile and provider, or `op=new_chat` on an idle window no session holds.
3. Before its first message on a new account or workspace: `op=run_macro window=<new handle> macro=connect-akimcp` (no option; `op=handoff_open` does it itself).
4. First message (`op=send`): its role, your handle, and what to read: `aki__aiobox op=read window=<your handle> last=30`. It reads, never asks.
5. The new chat renames itself for its role, then replies with its handle and chatId (`op=whoami`).

## Quota or interrupted replies: your role to another account

The numbers here win over any tool description.

1. Watch: `usage` in `op=whoami`: from 82% keep your state in your answers.
2. By hand, or once out of quota (no composer): `op=handoff_open profile=<id> provider=<p> like=<your handle> text=<role, your handle, what to read: chat, rules, working file, letter>` on another account with under 3 windows of the provider, then finish it. Your role's successor opens only this way, never by `op=new_window`. Any window can do it for one that cannot chat. Refused `<handle> already took over …`: finish or close it, retry. Refused at `like`: do as it says. `workspace: fallback (…)`: another workspace was used; `the page is on workspace …`: nothing sent, `op=switch_workspace`, then `op=send`.

## Chat cutoffs

A chat cutoff ("Resting" in AIObox) is a normal, temporary break from new AI chats on an account or workspace; keep helping the user. Until it clears (at `until`, or once the allowance is back), AIObox starts new AI chat work on another account; work done is kept.

`op=profiles` shows `canTakeChat` and `chatCutoff`. Tell AIObox what you saw: `aki__aiobox_write op=pause_chat reason=<what the chat showed>` with `account=<label> profile=<profileId> hours=4` (one account failing on ≥ 2 windows) or `workspace=<label>` (full quota or pause notice there; the account once on ≥ 2). `op=resume_chat` ends one.

Notion's words: "Interrupted" = an interrupted reply; "used your … allowance" and no composer = out of quota; "Stopped by a usage policy" = a pause notice.

## Finishing a handoff to another window

1. `aki__aiobox_write op=place_like window=<new handle> like=<old handle>`: takes the old one's place and size.
2. The successor reads `op=read window=<old handle> last=30` and tells every related window its handle.
3. `aki__aiobox_write op=close_window window=<old handle> successor=<new handle>` (even mid-answer; the chat is saved, a draft is not). Done only after all three.

## Notion: choosing the account and workspace

Each Notion profile: one account, several workspaces.

1. Usage per profile: `op=state` `workspaces`, skip any with a `status` (free, failed) or a chat cutoff. A workspace's use = max(`session`, `weekly`); an account's = its lowest workspace.
2. Pick the account with the fewest windows (`op=state`), then lowest use, below 87% (82% or more last).
3. Open its window: `op=new_window profile=<id> provider=notion` or `op=handoff_open` (`op=profiles` eligible).
4. In that account, use its lowest workspace (0% first). A new window or chat opens on Notion's last-used workspace; if not the picked one, `op=switch_workspace window=<handle> workspace=<label>` before the first message, then check AkiMCP (new window step 3).