# What HB Code is

> A desktop app that runs OpenAI Codex and Claude Code sessions on your projects. Each command, file, and diff opens with one click. The iPhone and Android apps control the same session through a relay. This handbook explains how it is built.

Handbook / Start here · Checked against the source on 2026-10-05 · https://www.hbcode.ai/docs

## What is different

HB Code is a Mac and Windows app that runs coding agents against a local project folder: OpenAI Codex on your ChatGPT subscription and Claude Code on your Claude account. This handbook explains the parts you cannot see from the screen: which process owns what, how a message becomes an agent turn and gets confirmed, how the timeline is assembled from history pages and a live overlay, what the relay does and refuses to do, and how the bundled tools reach your Chrome, Gemini, and your phones.

Each session runs one agent, Codex or Claude Code. You pick it when you create the session, on the desktop or on a phone, and it stays for the life of the session. The desktop remembers the last choice for the next new session and starts with Codex. Both agents use one chat layer, so the chapters below apply to both unless they say otherwise. The list shows what the two agents share. The table shows where they differ.

- The desktop starts the agent process and owns it.
- Every message goes through the durable outbox and has one operationId.
- A message that you send during a run joins the running turn. You can also put it in the queue of the session for later.
- One tool catalog in the namespace hbcode. Four tools are always in it.
- One scale of four access levels.
- Settings → Agents shows accounts, limits, and usage.

| Topic | Codex | Claude |
| --- | --- | --- |
| Process | A long-lived app-server child process. One child serves many sessions. | One Node process per run, the agent host, with the Claude Agent SDK. It ends with its run. |
| Delivery proof | Codex echoes the operationId as the clientId of the user message. | The saved transcript holds the message UUID of the operation. |
| A message during a run | turn/steer adds the message to the running turn. | The agent host writes the message into the open query. Claude reads it after its current step. |
| Tools | The thread keeps the list from its start. Codex runs these tools without asking. | Each run gets a new list. Claude asks by access level, except for session lookup and session messages. |
| Level names | Read only, Full auto, Full access, Never ask. | Plan mode, Accept edits, Auto mode, Bypass permissions. |
| Accounts | ChatGPT sign-ins, stored as Codex auth profiles. | The Claude sign-in of the computer and added account folders. |

- [Codex and Claude side by side](https://www.hbcode.ai/docs/agents.md): Process lifetimes, the dispatch layer, access levels, capabilities, and limits for both agents.

The drawing below follows one message of a Codex session from a phone to the agent. A Claude session takes the same path to the outbox and proves delivery from its saved transcript.

**A message stays on the phone until the desktop’s receipt, and in the outbox until Codex echoes it**

A message sent from a phone passes through the relay to the desktop, which saves it as an outbox entry and returns a receipt to that phone, and only then does the phone drop its own copy. The desktop starts a Codex turn with the operation ID as the client message ID and removes the outbox entry when Codex echoes that ID back. The relay only passes messages through: it keeps no queue and no replay log. Timeline updates then reach phones that hold an interest lease, and the phone’s row carries the same operation ID. If the reply to turn/start is unclear or the desktop restarts before the echo, the desktop looks for the operation ID in the session history.

- **Receipt** (queueId · operationId): Returned as soon as the message is saved in the desktop outbox, and only to the phone that asked. The phone waits up to 20 s for it and keeps its own copy until it arrives.
- **Codex echo** (userMessage.clientId): The drain task sends the operationId as clientUserMessageId. When the live item/completed notification carries it back, the desktop records the message as sent and removes the outbox entry.
- **No desktop connected** (-32011 · -32010): The relay answers the phone itself: -32011 while the desktop is reconnecting, -32010 once it is offline. Nothing is queued, and the phone keeps its copy.

## The three rules of the design

- The desktop is the authority. It owns the project files, the agent processes, the durable outbox, and the RPC router that phones talk to.
- The relay is dumb on purpose. It routes envelopes between authenticated devices and holds no project contents, no durable queue, and no replay log.
- Every timeline row is a typed object with a stable identity, so the same conversation renders identically on the desktop and on a phone without text matching or timestamps deciding what exists.

## Chapters by subject

- [Setup: sign-ins, regions, remote access](https://www.hbcode.ai/docs/setup.md): The HB Code, ChatGPT, and Claude sign-ins, one region per account, the remote-access switch, and the preview before Pro.
- [Process boundaries](https://www.hbcode.ai/docs/architecture.md): The four application boundaries, the two agent process boundaries, and a mobile request traced to execution.
- [The Claude Agent SDK integration](https://www.hbcode.ai/docs/claude-agent-sdk.md): The agent host, how Claude’s saved lines become timeline rows, approvals, subagents, and accounts.
- [Message delivery](https://www.hbcode.ai/docs/message-delivery.md): Outbox custody, turn admission, the agent’s delivery proof, and what happens when a reply is lost.
- [Timeline](https://www.hbcode.ai/docs/timeline.md): History pages, the revisioned live overlay, settlement epochs, and the pagination splice contract.
- [Storage ownership](https://www.hbcode.ai/docs/storage.md): appdata.db, the Codex profile home, Claude’s own folder, PostgreSQL, and the exact-source rules for transcripts.
- [Relay wire protocol](https://www.hbcode.ai/docs/relay-protocol.md): Envelopes, registration, pending-request correlation, and the two idempotency layers.
- [Browser Bridge](https://www.hbcode.ai/docs/tools/browser-bridge.md): Native messaging, Chrome DevTools input, incognito research windows, and upload validation.
- [Build, test & contribute](https://www.hbcode.ai/docs/contributing.md): The sidecar build, the checks per boundary, and how to trace one operation through the code.