Skip to article
HB CodeDocs
Get the app

HandbookBundled tools

Documents, speech, video, alerts, session lookup

The rest of the plantocode namespace: self-contained HTML documents, Gemini text-to-speech and video extraction under your own key, push alerts through the relay, and a read-only view of your sessions.

Checked against the source on 17 September 2026

On this page

What the agent can reach

Gemini and phone tools exist only if they were set up before the session started
Gemini and phone tools exist only if they were set up before the session startedThe Codex child asks the desktop runtime to run every plantocode tool, and it keeps the tool list its session started with. Three tools act on this computer and are always in the list: HTML files in the app data folder, a read-only look at your sessions in appdata.db, and your Chrome. Speech and video go to Gemini and exist only if a Gemini key was saved. The phone alert goes through the regional server to your phones and exists only if notifications were on. Saving a key or turning on notifications later only affects sessions that start afterwards; deleting the key or turning notifications off stops those tools at once.
this computer
off this computer
Codex childkeeps the tool list it started with
Desktop runtimeruns every tool
create_html_document
HTML files
maintain_sessions
Your sessions
use_user_browser
Your Chrome
synthesize_speech
extract_video_context
Gemini
only if a Gemini key was saved
send_mobile_notification
Your phonesvia the regional server
only if notifications were on
Saving a key or turning on notifications later only affects sessions that start afterwards.
  • Tool callitem/tool/call

    Codex asks the desktop to run a tool and waits for the reply. The request names the calling thread, and the desktop routes it to that thread’s session and active run. The model’s arguments carry only the task.

  • Local toolsbuild_app_capabilities

    Always in the list: HTML files under agent-documents in the app data folder, a read-only look at appdata.db, and your Chrome through Browser Bridge, which stays off until you enable it.

  • Conditional toolshas_gemini_api_key · show_notifications

    The Gemini pair needs a Gemini key saved on this computer and calls Gemini straight from the desktop. The alert needs Desktop and phone notifications on and travels through the regional server. Both conditions are checked again on every call.

  • Fixed listdynamicTools

    Codex takes the list only when a thread starts, so a resumed session keeps the tools it began with. The specs hold no session or run values, so nothing in them goes stale.

HTML documents

The agent can answer with a complete HTML document, with inline CSS, SVG, and scripts, that opens in the desktop preview pane and in the file viewer on your phone. It loads no external assets. The desktop serves it from a sandboxed origin, and the app accepts only two messages from the page: open a link, and page loaded.

The tool takes a title of at most 120 characters and a plain-text brief of at most 64 KiB. It starts a private document agent on the current Codex account to design the page, create useful SVG diagrams, save the HTML, and review the result. Drafts and worker tool activity stay out of the main chat. The call returns when the worker finishes, with a saved Markdown link, reported checks, and any review limits. The worker can revise the same document and must repeat review after edits. A checked visual review requires a screenshot of the latest preview and an image-view event; when review is unavailable, the result must state why. This evidence does not certify design quality or factual accuracy. Documents are limited to 2 MiB, must be self-contained and structurally valid, and receive a Content-Security-Policy that blocks external resources and network requests. They persist under agent-documents/<sessionId>/<documentId>/ in the desktop data directory with metadata.json. The main agent must include the returned Markdown link verbatim.

Speech and video with your Gemini key

Save a Gemini API key in Settings → API Keys and two more tools appear in the namespace in sessions that start after you save it. Both read the key on every call, so deleting it stops them at once, also in sessions that still list them. The key stays on the desktop, and the requests go from your computer straight to Gemini.

  • Text-to-speech. The desktop splits the text at sentence boundaries into chunks of at most 1,800 characters, synthesizes three at a time with gemini-3.1-flash-tts-preview, retries each chunk twice with a growing backoff, and stitches the 24 kHz mono 16-bit PCM parts with 180 ms of silence between them into one WAV file under agent-speech in the cache directory. Director notes stay outside the spoken transcript, and a multi-part prompt tells the model not to read the part number aloud. Thirty prebuilt voices are available and Kore is the default.
  • Video context. The source is a public YouTube URL, a public https video URL, or a local recording, with a tutorial or meeting intent. A YouTube ID must be 11 characters and a playlist parameter is rejected. gemini-3.1-pro-preview runs at temperature 0.2 against a JSON schema that is rendered to Markdown. Tutorial mode extracts concepts, procedures, commands, code, on-screen text, and caveats; meeting mode extracts decisions, requirements, blockers, action items, and open questions. The result is timestamped notes scoped to your goal, with gaps called out.

Video sources are exactly one of youtube_url, local_file, or video_url. A remote URL needs one of twelve supported video MIME types such as video/mp4, video/webm, video/quicktime, or video/mpeg, and Gemini must be able to fetch it directly. There are no fallbacks: a private, inaccessible, or ambiguous source fails explicitly.

Alerts written by the agent

A successful alert call only means the desktop queued it for the relay
A successful alert call only means the desktop queued it for the relayThe agent’s send_mobile_notification call returns as soon as the desktop queues the event on its device link. If a link that has started is not ready, the desktop restarts it and tries 8 more times 250 ms apart, so the agent gets an error after about 2 seconds. Past the relay nothing reports back: a server without APNs or FCM, an account without a registered phone, and a rejected token are only logged, and a phone without notification permission shows nothing. The tool exists only in sessions whose Codex thread started while Desktop and phone notifications were on, and it sends nothing once the setting is turned off.
The tool exists only in sessions whose Codex thread started while notifications were on.
requested, once queued
Codex turnsend_mobile_notification
Desktop runtimedevice link
past here, nothing reports back
Regional serverevery phone on the account
APNs · FCM
Phones
no APNs or FCM, or no phone registered: logged
token rejected: logged
notifications not allowed: nothing shown
not ready: restart, then 8 tries 250 ms apart
0 s
2 s
could not be requested
  • Requestedagent-notification-requested

    The call returns as soon as the event is queued on a connected device link. The server broadcasts it and sends the pushes afterwards, on its own.

  • Visible failureinitialize_connection

    If the link is not ready, the desktop restarts it and tries 8 more times. With Allow Remote Access off or while signed out it never comes up, so the error arrives after about 2 seconds, or at once if the link never started since the app launched.

  • Silent dropsend_agent_notification_push

    After the relay nothing comes back. A server without APNs or FCM, an account with no registered phone, and a rejected token are only logged. A phone without notification permission shows nothing.

Turn on Desktop and phone notifications in Settings → General and sessions started after you turn it on get a tool for one push alert about the current session per call. The desktop checks the setting again on every call, so turning it off stops alerts at once, including from sessions that still have the tool. Each alert names the session and the run that is active when the agent calls the tool. The Agent notifications row below it selects the guidance the tool carries from the start of a session: Important limits it to results and blocking questions, Frequent adds meaningful milestones and failures but still tells the agent to avoid routine progress updates. Both policies expose the same tool; only its description differs. The 60-character title cap forces the outcome first.

Session lookup

maintain_sessions is a read-only view of appdata.db with three actions: guide, listSessions, and resolveSession. It joins sessions with the project workspace state, which marks the active session, and with the Codex session links, orders by last update, returns 25 rows by default and at most 200, filters by the hash of the project directory, and resolves an HB Code session to its Codex thread link. It cannot update session metadata or active-session state, and it is not a SQL tool.

Where the data goes

Browser control operates your Chrome, speech and video send text or video to Gemini under your key, and alerts travel through the regional server.

Local execution still uses remote services

Every destination that receives data, and what desktop-owned does and does not mean.