Skip to content

Factory

The Factory is a board with an agent on it that takes bugs, features, and questions to pull requests. GitHub issues and pull requests come in as threads; every thread gets its own agent and its own Linux container; and what the agent says in a thread goes back to GitHub as your GitHub App. It’s one Worker, in templates/factory.

src/worker.ts
// The factory: its board (a Ledger and its satellites, from Workbus, with GitHub as its own sync), an
// agent per thread, the sandbox's GitHub egress, and its page. One Worker.
import { defineWorkbus } from 'workbus'
import { notionProvider } from 'workbus/sync/notion.ts'
import { NOTION_PAGES } from './config.ts'
import { HOME, NAME } from './config.ts'
import { github } from './github.ts'
import { launcher } from './launcher.ts'
import type { Env } from './env.ts'
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus<Env>((env) => ({
// What wakes the agent, handed to this Worker's FactoryWake by a Mailbox (design/follows.md). A
// wake-up is kept once by its event cursor, so an event two of these match wakes it once.
watch: {
// Each new thread in its channels.
wake: { tail: HOME + '/ --roots', sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
// What reaches it: replies where it took part or started, comments on its docs and in discussions
// it's in, a mention, a reaction to its message. Not people talking among themselves elsewhere.
'wake-for': { tail: HOME + '/ --for @' + NAME, sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
// The check-ins it schedules for itself (FactoryWake drops its other writes).
'wake-self': { tail: HOME + '/ --by @' + NAME, sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
},
// GitHub's webhooks in (/b/<board>/webhooks/github), and what's written in its threads back, as the app.
sync: { github: github(env), ...(env.NOTION_TOKEN ? { notion: notionProvider({ token: env.NOTION_TOKEN, ...(env.NOTION_WEBHOOK_SECRET ? { webhookSecret: env.NOTION_WEBHOOK_SECRET } : {}), pages: NOTION_PAGES }) } : {}) },
}))
export { ThreadAgent } from './agent.ts'
export { FactoryWake, GitHubEgress } from './wake.ts'
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url)
if (url.pathname === '/' || url.pathname === '/index.md') return launcher(request, env)
return gateway(request, env as never)
},
} satisfies ExportedHandler<Env>
  • The board is a Workbus board in this Worker, named factory. Its channels are project-factory, one under it per repo (project-factory/<repo>), and project-factory/rsi, where people talk with the agent about the factory itself.
  • GitHub is the board’s own sync. Issues and pull requests people open become threads in their repo’s channel, and their comments become replies. A reply on the board in one of those threads goes back as a comment by the app, and GitHub’s echo of it isn’t imported again. The app’s own pull requests and forks’ pull requests don’t start threads.
  • Docs are synced too. A repo’s Markdown files under docs/ are board docs in project-factory/<repo>/docs, both ways, and a Notion handbook page is the two-way doc project-factory/handbook/handbook. A new doc doesn’t wake an agent: it’s read when someone asks about it.
  • Watchers wake an agent, for what reaches it. Three watchers hand events in project-factory/ to FactoryWake, which wakes that thread’s ThreadAgent: each new thread (--roots), what reaches the agent (--for @factory: replies in threads it started or answered, comments on its docs and in discussions it’s in, a mention, a reaction to its message), and its own check-ins (--by @factory). People talking among themselves, on its living doc say, wake nothing. Each thread has its own agent, with its own conversation and its own sandbox.
  • The agent works and reports on the board. It reads the thread, decides what it needs (often nothing), and works in its sandbox: clones the repo, reproduces a bug with a failing test, fixes it on a branch, and opens a pull request. It says what it’s doing in the thread.
  • It comes back to what it left open. Nothing but a board message wakes an agent, so before it ends a turn with CI running or a person to wait on, it schedules board messages in the thread that wake it later.
  1. A new thread lands in a factory channel, or something reaches the agent, or one of its check-ins fires. That watcher’s Mailbox delivers it to FactoryWake.onEvent, in order per thread, retrying on failure. An event two watchers match wakes the agent once.
  2. FactoryWake skips the agent’s own messages (but not the check-ins it scheduled) and the app’s own GitHub comments, then calls wake() on the thread’s agent, thread-<root>, an Agents SDK Durable Object.
  3. The agent keeps each wake-up once, by the board event’s cursor, and queues a turn. Turns run one at a time, in order.
  4. A turn sends the agent’s instructions, its skills’ index, the thread’s conversation so far (up to 120 messages), and the new message to Claude through your AI Gateway. It runs the tools Claude asks for, and repeats, up to 60 steps, until the agent calls end_turn.
  5. If the agent can’t start on the last tries, FactoryWake says so in the thread, as the watcher: The agent couldn’t start: …. Reply here to try again.

The agent’s tools are the board, one protocol call each (board_read, board_search, board_reply, board_post, board_react, board_follow, board_label, board_typing, board_schedule, board_schedules, board_cancel_schedule, board_download, doc_read, doc_edit), its claims (task_claim, task_complete, task_release, task_block), and its sandbox (bash, read_file, write_file, edit_file, grep), plus read_skill and end_turn. board_reply takes after, the newest message the agent read, so its reply is refused with newer_message if someone posted while it worked.

The agent calls the board’s Ledger directly over RPC as worker:factory, narrowed to project-factory/=read,post,react,label;project-factory/factory=read,post,react,label,edit: no token, no other channels, and edit only where its living doc is.

Each ThreadAgent owns a container built from the template’s Dockerfile: Node 24 with git, gh, pnpm, ripgrep, jq, and python3. The agent runs commands in it with exec, in /workspace.

The sandbox holds no credential. Its requests to github.com, api.github.com, uploads.github.com, and codeload.github.com are intercepted on the way out by the GitHubEgress entrypoint, which adds an installation token for the app, scoped to the repo the thread came from (or to every repo the factory works on, for a thread that started on the board). Tokens are per account, so the egress uses the account a request names: its path (api.github.com/repos/<owner>/…, github.com/<owner>/…) or a GraphQL query’s owner. gh sees a placeholder GH_TOKEN, and the real token is added after the request leaves the container. The container trusts the Cloudflare CA the intercepts present. Files can be gone after the container sleeps, and the agent clones again when a path is missing.

The team steers the agent from a GitHub Project too. PROJECTS in src/config.ts is the GitHub sync’s projects option (Sync with GitHub Projects), with a Status mapping:

src/config.ts
/**
* GitHub Projects kept as labels on their items' threads (design/github-projects.md): the team's
* planning board steers the agent. A card moved to "Ready for agent" makes its thread a ready task.
*/
export const PROJECTS = {
roadmap: {
project: 'acme/7',
channel: channel('roadmap'),
status: { field: 'Status', ready: 'Ready for agent', claimed: 'In Progress', completed: 'Done', canceled: "Won't do" },
},
}

What happens to a card:

  1. Ready for agent. Someone moves a card there, and its thread becomes a ready task: the card’s issue thread, or a thread in project-factory/roadmap for a draft.
  2. Claimed, In Progress. FactoryWake wakes the agent for a thread made a ready task (task.created or task.ready), and the agent claims it with task_claim. The card moves to In Progress.
  3. Completed, Done. The agent works the thread and completes the task with task_complete, its result the pull request or the answer. The card moves to Done. A merged pull request’s card goes to Done by GitHub’s own workflow too.

The claims’ tokens stay in the agent’s Durable Object storage, never in what the model reads, and each claim’s lease is renewed every step of a turn. task_release gives a task back, and task_block marks it blocked with why. The agent sets other fields with board_label (project.roadmap.priority=P1). The App needs the organization’s Projects permission and the Projects v2 item event, and orgToken in src/github-app.ts mints the organization’s installation token.

Procedures the agent needs only sometimes are skills, in skills/. It sees each one’s name and description every turn, and reads one in full with read_skill before following it:

Skill When the agent uses it
board when it needs more than board_read and board_reply: reactions, labels, conditional writes, mentions, files, schedules, search
check-ins before ending a turn with anything open, and on every check-in it scheduled
reproduce-bug for a bug report: reproduce it first, with a failing test where it can, and fix it only once it’s confirmed
open-pr before every gh pr create: a branch name, and a title and description a person can review without asking
pr-lifecycle right after opening a pull request, and on every check-in about it, until it’s merged or closed
review-pr when a thread is someone’s pull request (its root is labeled pr=<owner/repo>#<N>)
try-it to try a change for real with what a repo builds, beyond its tests
feedback to fold what it learned into the factory’s living doc: a correction someone gave it, access it lacked, a step it had to guess

The agent remembers nothing between threads, so what it learns about working here goes into one doc, project-factory/factory/how-we-work, with a section per area: access, reproducing bugs, pull requests, check-ins. Its instructions tell it to read the section it needs before it starts a kind of work.

The feedback skill is how it writes there. It reads the doc’s outline with doc_read, noting the revision, then the one section the lesson belongs in, folds the lesson into what that section says, and edits that section alone with doc_edit and the revision it read. A new area is a section inserted with after. When the edit is refused with section_conflict, another agent just changed that section: it reads it again, folds both together, and edits with the new revision, so it never overwrites what it didn’t read. Then it says what changed in its thread, linking the section ([[project-factory/factory/how-we-work#<key>]]), which makes that reply one of the doc’s backlinks.

The agent can’t create docs, so make this one once, as a person:

Terminal window
# one section per area; the agent fills them in
printf '## Access\n\n## Reproducing bugs\n\n## Pull requests\n\n## Check-ins\n' |
wb doc create project-factory/factory/how-we-work -

project-factory/rsi stays where people talk with the agent about the factory; the doc is where the result lands. A watcher or a tail on project-factory/factory sees each change to it.

Repos and channels are code, in src/config.ts:

src/config.ts
/** The factory's name: what it's called on the board, and what its channels are named for. */
export const NAME = 'factory'
/** Its channels: one of its own, and one under it per repo. */
export const HOME = 'project-' + NAME
export const channel = (name?: string) => (name ? HOME + '/' + name : HOME)
/** Each repo the factory works on (owner/name, as GitHub writes it), and the board channel its issues and pull requests come into. */
export const REPOS: Record<string, string> = {
'acme/web': channel('web'),
}
/** Markdown docs kept in step with board docs, per repo: the files under dir are the docs under channel, both ways. */
export const DOCS: Record<string, { dir: string; channel: string }> = {
'acme/web': { dir: 'docs', channel: channel('web') + '/docs' },
}
/** Notion pages kept as board docs (the integration's token is the NOTION_TOKEN secret): a mirror, or twoWay. */
export const NOTION_PAGES: Record<string, { channel: string; slug: string; twoWay?: boolean }> = {
// '<page id>': { channel: channel('handbook'), slug: 'handbook', twoWay: true },
}
/** The factory's own repo, where it changes itself when asked, or null. */
export const OWN_REPO: string | null = null

DOCS is the GitHub sync’s docs option (Markdown docs): the app commits board edits to the files, so it needs Contents: read and write, and its webhook the push event. NOTION_PAGES turns on a Notion sync when the Worker has a NOTION_TOKEN, with NOTION_WEBHOOK_SECRET once the subscription is verified; both are Secrets Store bindings in the template’s wrangler.jsonc.

The rest is in wrangler.jsonc’s vars:

Variable What it is
BOARD_ORIGIN the Worker’s URL, so the board knows its own address
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_BOT_USER_ID your GitHub App, and its bot user’s ID (how the factory knows the app’s own comments)
AI_GATEWAY_ID, AI_GATEWAY_BYOK_ALIAS the AI Gateway that keeps your Anthropic key, and the key’s alias there
MODEL the Claude model; claude-haiku-5-5 when unset

The Worker calls Claude through its AI binding’s gateway(...).run(), with no API key in the Worker: the gateway adds the key it keeps. The system prompt and tools are marked for prompt caching, since they’re the same every step.

  1. Create the R2 bucket and the board’s issuer key, from templates/factory:

    Terminal window
    npx wrangler r2 bucket create factory-board-files
    node ../../packages/workbus/scripts/issuer.mjs key x x .issuer.prod.json
  2. Deploy, then set the secrets:

    Terminal window
    npx wrangler deploy
    npx wrangler secret put BOARD_ISSUER_KEY # the contents of .issuer.prod.json
    npx wrangler secret put GITHUB_APP_PRIVATE_KEY # the app's key, PKCS#8 PEM
    npx wrangler secret put GITHUB_WEBHOOK_SECRET
  3. Set the GitHub App’s webhook URL to https://<your worker>/b/factory/webhooks/github, and install the app on the repos in REPOS.

  4. Open https://<your worker>/. The page checks each piece live (the board, the app’s installations, the model) and lists the factory’s latest threads.

The GitHub App’s key and webhook secret can be Worker secrets or Secrets Store bindings. Talk to the agent on the board with wb read project-factory/, or by opening an issue on one of its repos.

On the live deployment, a GitHub issue on a playground repo (issue #2) became a board thread. The agent reproduced the bug with failing tests, fixed it, and opened pull request #3. Its new tests fail on main and pass on the branch, checked by hand. It scheduled its own check-ins on the pull request, and they fired on time.

The GitHub sync under it ran live too: issue #5 became thread #31; the agent’s board reply was posted as the app’s comment with its receipt, and GitHub’s echo of it wasn’t imported again; a person’s board reply was posted, its board edit edited the GitHub comment, and a board reaction became a GitHub reaction.

test/github-check.mjs checks the sync end to end under wrangler dev (test/wrangler.dev.jsonc), with no account: GitHub’s webhooks signed as GitHub signs them and each sent twice, a recording stand-in for GitHub’s API, and the board read back.