---
version: 51
---
# 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/` (`~/.aki/aiobox/` is the app's).

## 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: 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.

## Picking a window: pool or account, then ready

Every new window comes from these steps and keeps a role only once ready (step 4); a role's successor starts at step 2.

1. Pool: an idle window no session holds, on an account that can take chat (`op=profiles` `canTakeChat`): `op=new_chat window=<handle>`. None: step 2.
2. Account: another than yours, under 3 windows of the provider; fewest windows, then lowest use, below 87% (82% or more last). Use, from `op=state` `workspaces`: a workspace's = max(`session`, `weekly`), skipping one with a `status` (free, failed) or whose `canTakeChat` is false; an account's = its lowest workspace. Open its window: `op=new_window profile=<id> provider=<p>`; a role's successor: `op=handoff_open` (it does steps 3-4 itself).
3. Init: Notion opens a new window or chat on its last-used workspace; if not the account's lowest (0% first), `op=switch_workspace window=<handle> workspace=<label>`. On a new account or workspace: `op=run_macro window=<handle> macro=connect-akimcp` (no option).
4. Ready: AkiMCP answers in it, so its first reply carries its handle and chatId (`op=whoami`). Not ready: redo step 3, or pick another.

## 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 it (Picking a window).
2. 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.
3. It renames itself for its role; its first reply is the ready of Picking a window step 4.

## 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 an account picked as in Picking a window step 2, then finish it. Timed out: op=runs (no args), find the row with request=<id>; don't hand off by hand while that run is still going. 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; `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 its `until`, new AI chat work goes to another account; work done is kept.

`op=profiles` shows `canTakeChat` (per account and per Notion workspace; false when full, resting or unread) and `chatCutoff` (a rest only; a full quota is never one). 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>` (pause notice there; the account once on ≥ 2). `op=resume_chat` ends one; every pause ends (default 4 h).

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.