The build agent

The build agent is an agent that lives in an AI agent room, works against your real repository, and delivers every change as a pull request. You describe what to build — or hand it a story from a Kanban board — and it edits files, commits on a branch, and opens a pull request for you to review. It never merges.

It does not run the code it writes. It reads the repository, edits files, commits and opens a pull request; your own CI runs the tests on that pull request. No untrusted code executes on Openbook's infrastructure.

This page walks the full workflow. The room type itself is covered in AI agent.

What an agent room is

An AI agent room is a room connected to a repository. Its left rail organizes everything the agent works with:

• Chats — your conversations with the agent.
• Knowledge — reference material the agent loads.
• Workflows — recurring or triggered automations.
• Assets — files the agent produced.
• Skills — reusable instructions.
• Integrations — external tools the agent can use.
• Actions — custom tools you define.
• MCP — tool servers you connect.
• GitHub / GitLab — repository connections.
• Settings — room configuration.

Connect a repository

Openbook connects to GitHub and GitLab, and both can be connected at once. A connection is made once per host per organization, with a personal access token — not an installed app — so the token is entered in one place and rotating a departing teammate's token is one edit rather than a hunt.

1. Open the room's GitHub or GitLab panel and paste a personal access token. This is the identity the agent commits and opens pull requests as.
   • GitHub — a classic token with the repo scope, or a fine-grained token with Contents, Pull requests and Webhooks read and write.
   • GitLab — a token with the api scope. A project-level token works, but only for that project.
2. Add one or more repositories. Paste owner/name, or just paste the repository's URL.
3. Choose "This room builds here" on the repository this room should work in.
4. Set which branch new branches are cut from. The default is main.

The token is never stored until the host has accepted it. If the scopes are wrong you find out while pasting, not on the first run.

Self-hosted GitHub Enterprise and self-managed GitLab work too — give the connection your own API base URL.

Revoking a connection clears the token and stops the updates, keeping the board's history. Deleting one removes the pull-request mirror entirely.

Brief the agent

You talk to the agent in the room's chat. Describe what to build in plain language, or use the composer's shortcuts:

• # opens a board and story picker. Pick a Kanban board, then a story. The card becomes the specification: its description and checklist are what the agent builds from. Stories show their reference keys (OB-3 style), and filters hide done and backlog stories so you are choosing from live work.
• / offers commands.
• Drag files in to give the agent designs, logs, or anything else it should look at. A text file is read inline; an image is passed as an image.

Writing the spec as a story pays off twice: the card's checklist gives the agent concrete acceptance criteria, and everything the run produces stays attached to the story afterwards.

Choose how much it may do alone

The room's autonomy setting is a four-rung ladder:

Mode	Shown as	What it does
auto	Work unattended	Reads, edits and opens a pull request without stopping.
accept	Accept edits	Works unattended, but the pull request opens as a draft — the work lands, a person lifts the gate.
ask	Ask before committing	Investigates and edits freely, then waits for you before it creates a branch or opens a pull request.
plan	Plan only	Reads, thinks and writes a plan. It cannot change a file.

The same ladder governs external tools, and irreversible outside-world actions only run in auto — see Agent integrations.

Watch the run

When the agent starts, a run appears with live steps and streams as it goes. You can watch it work: it reads files, searches the code, edits, then creates a branch, commits, and opens a pull request — it never merges. Merging is always a human decision made in your code host.

Every pull request body ends with a line saying it was opened by the build agent and is up for review.

Run statuses include Needs review, Awaiting approval and Failed, so you can tell at a glance which runs are waiting on you and which hit a wall.

A run stops on its own when it reaches the room's step limit (80 by default, adjustable from 4 to 200) or its token budget per run, and says which. Reaching the token budget stops the run at a turn boundary and keeps everything it had already done: Stopped at the room's per-run token cap.

Cancelling marks a run cancelled. A run already finished or failed is left alone, and an in-flight loop is not interrupted mid-commit — there is no safe point to cut it.

When a run waits for approval

In ask mode, and whenever a verification pass disagrees with the result, the run pauses at awaiting approval with its edits staged rather than committed. You review the staged files and either approve — which commits them and opens the pull request — or discard them, which cancels the run and writes nothing.

If the staged files change between your approval and the commit, the commit is refused and you are asked to review again. Nothing is committed on a stale approval.

Verification runs

A room can require up to three verification passes on every run, where separate judges check the result before it lands. A dissent sends the run to approval rather than failing it, so a disagreement becomes a question for you rather than a discarded afternoon.

When the agent has questions

If a run came from a card and the agent hits an ambiguity mid-run, it does not guess silently — it posts its questions in the card's Discussion as numbered options. Reply with @agent and your answer, and the run continues with your decision.

What attaches to the story

Research documents and screenshots the agent produces during a run attach to the story, up to 10 files. The card ends up carrying both the specification and the evidence of how it was built.

Review the pull request

When the run finishes, the chat shows a "Review the pull request" button that takes you straight to it. Review it as you would any teammate's work: read the diff, run it, comment, request changes, and merge when you are satisfied.

The agent's hard boundary is the pull request. It can propose any change but land none — nothing reaches your base branch without a human merging it.

Three backends

The room chooses who actually does the work:

Backend	What it is
Built-in agent	One conversation with this room's model and tools. The default.
Agent team (CLI)	A coordinator plans a small graph of tasks — up to twelve, three at a time — and each task runs its own agent in its own clone in a scratch directory.
Codex subscription	The room's assigned personal Codex agent, running on somebody's connected ChatGPT plan. Each task needs exact approval.

The first two arrive in the same staging area, so approval, verification and the commit work identically. An organization owner can switch team mode off for a whole space with the per-space agent gates.

Codex subscription runs

This backend runs on a personal agent connected to a ChatGPT subscription rather than on an API key — see Reusable & personal agents. Two things follow from that.

First, every task is approved individually. A dialog headed Review this Codex subscription request appears with the exact settings the server resolved — task type, funding, connection, agent, model, permission, token limit, runtime ceiling, source, room control, result, publication policy — plus the exact instructions, skills and granted tools if you want to open them. You press Approve and start. Its description is the reason it exists: "These are the exact server-resolved task and settings. A change requires a fresh review." A change means a fresh review, not a re-used approval.

Second, somebody's personal plan is paying. Worker funding offers your own connected subscription or an owner's grant, shown with its limits and expiry. Using someone's grant tells you so plainly: "Your request will run as approved bot work on the owner's private worker and use their connected plan. Your identity stays on the request and result."

Where the result lands is a room setting: New branch for each result or Update the source branch, with a delivery branch and a pull request target. Existing-branch delivery uses the exact source SHA and never force-updates the pull request target.

Reviewing an artifact before it is public

Codex results arrive in an Artifact review panel, marked "Proposed public output · private until approved". You read the exact bytes and then press Approve exact artifact and publish draft PR.

The approval is deliberately narrow: it binds the displayed bytes, modes, destination, public text and policy revision. It may create one draft pull request. It never merges.

Automatic story pickup

A room can take Ready stories off a board on its own, using a personal Codex agent, under Automatic story pickup in room settings. The subtitle states the scope: "Uses your Codex subscription for the exact board, repository, agent and limits shown here."

Press Add rule, then set a Name, a Mode (Matching Ready stories or One approved card), the Board, the Ready column, and any narrowing you want by story priority or title. One checkbox decides how much history it takes on:

Include stories already in Ready. Off by default, so activation only applies to newly Ready work.

Before it starts, the panel restates the whole arrangement in one line — private output, whose subscription, jobs per day, concurrent jobs, retries, minutes per run, expiry date — and you press Confirm and enable. Individual rules can then be paused and resumed.

A reusable agent in this room

Everything on this page describes a room's own configuration. A room can instead inherit its instructions, permissions, limits and skills from a reusable agent shared across the organization, connected from the workspace's Agents directory.

When one is connected, the top of room settings shows each line with its origin — From <Name> v3 for anything inherited, Only in this room for anything this room narrowed — so it is always clear which setting is the agent's and which is yours. A room can narrow what the agent asks for; it can never widen it. When no agent is connected, the panel says so: "No reusable agent is connected to this room, so everything below is this room's own."

See Reusable & personal agents for the directory, versions and sharing.

Sessions

Conversations in the room are separate sessions, each with its own history. A room can be set to shared sessions, where any member can read and join the room's latest conversation instead of each person having their own.

Deleting a session removes the conversation but keeps its runs — those opened branches and pull requests that exist.

Oversight

The agent's work is auditable at the organization level, for the organization's owner and its admins:

• Organization → Chat logs shows every agent conversation across the organization, drilled down by space, room and session.
• Organization → Analytics shows sessions, messages, runs, active users, tokens used (in and out), runs by status, the top topics, a per-space breakdown, and a 30-day activity strip.
• Organization → MCP lists every MCP server across every room — see MCP servers.

The organization's owner can also set per-space agent gates at Organization → AI self hosted: force the single-agent backend, require verification runs, or cap the tokens one run may use.

What a run costs. It runs on whichever key your organization's AI configuration names. In self hosted mode that is your own key, your provider bills you directly, and nothing is capped. In managed mode it is the platform's key, and every token counts against the organization owner's allowance — a run that starts when the allowance is spent is refused before any provider is called, and one that is already running is not retried. The numbers Analytics shows are Openbook's own measurement of each run; the figure that decides anything is the one on the AI page's bar. See AI usage & the token allowance.

Going further

The chat is only the front door. To make the agent more capable in this room:

• Connect external tools under Integrations — see Agent integrations.
• Automate recurring work with Workflows and define custom Actions — see Workflows, actions & skills.
• Extend it with your own tool servers — see MCP servers.
• Point your own Claude or ChatGPT at a board from the other direction — see Board MCP server.
• Save this room's setup as an agent other rooms can use — see Reusable & personal agents.