What OctoStaff is

OctoStaff is a framework for durable collaboration between people and AI agents. Its organizing idea is that a conversation is not a request/response call to a model — it is a shared, append-only log that many participants read and write at the same time.

That one decision is what the rest of the platform follows from. A person and three agents can sit in the same thread. An agent can go offline mid-task and pick the thread back up on restart, because the thread — not the agent's memory — is the source of truth. A second agent can watch what the first one did, because it is reading the same log.

The shape of the problemCopy link to heading

Most agent integrations are shaped like a function call: you send a prompt, you await a completion, and the conversation lives in whatever your client happens to keep in memory. That shape breaks down as soon as you want any of the following:

• More than two participants. Two humans and an agent, or two agents with different tools, need a conversation none of them privately owns.
• Survival across restarts. A process that dies mid-turn should be able to rejoin and see what it missed, without replaying the user's work.
• Observability. If the agent's activity is a stream of events on a log, tool calls and approvals are inspectable records rather than opaque internals.
• Interruption. A long-running agent turn has to be cancellable by someone who is not the caller.

OctoStaff answers all four the same way: put the conversation in a sequenced event log, give every actor an identity, and gate every read and write with capabilities.

The piecesCopy link to heading

Bubble is the only piece that is strictly required. Everything else is opt-in: a connector is how a particular agent runtime joins, and Starfish and the terminal client are two ways to render what is happening — the HTTP and WebSocket protocols are public, so your own client is equally valid.

How a turn travelsCopy link to heading

   person                Bubble server                 connector          agent
     │                          │                          │                │
     │  append message_part     │                          │                │
     ├─────────────────────────►│                          │                │
     │                          │  assign seq, broadcast   │                │
     │                          ├─────────────────────────►│                │
     │                          │                          │  drain turn    │
     │                          │                          ├───────────────►│
     │                          │                          │                │
     │                          │                          │◄───────────────┤
     │                          │  append run_started,     │  tokens, tools │
     │                          │  message_part, tool_*    │                │
     │                          │◄─────────────────────────┤                │
     │  live frames             │                          │                │
     │◄─────────────────────────┤                          │                │

Four things are worth noticing in that path:

1. The person and the agent write the same way. Both append events to a thread; neither calls the other directly. Adding a second agent changes nothing about how the first one works.
2. Sequence numbers come from the server. Every subscriber sees the same events in the same order, which is what makes a replay after reconnect agree with what the live subscribers already saw.
3. The connector decides when a turn is ready. It buffers incoming events and drains them to the agent at a turn boundary, rather than forwarding every keystroke-sized delta.
4. Tool activity is on the log too. Approvals and results are events, so a reviewer can see and answer a tool request from any client.

What to read nextCopy link to heading

Start here if you want it running:

• Quickstart — a Bubble server, a bot principal, a thread, and a connected agent, from an empty directory.

Then follow whichever thread matches your goal: