Quick start

1. Install

Factory goes in your project as a dev dependency.

bun add -d @frebreco/factory

Bun 1.4.1 or later is required. Factory ships TypeScript and runs on Bun. You also need the opencode CLI, logged in (that’s the agent doing the work), and gh, authenticated (that’s what opens the pull requests).

2. Initialize

bunx factory init

That writes a config and one small workflow, and adds the right lines to your .gitignore. init reads your repo’s origin remote and git identity to fill the config in, so there is usually nothing to edit. Open .factory/factory.config.ts and check the repo block points at the repository you want pull requests opened against.

3. Start the daemon

bunx factory serve

Open http://localhost:3000. That’s the run monitor: every run, its live transcript, and a button to start a new one.

4. Run something

From the UI, hit New run, pick hello, and fill in the form. Or from a terminal:

bunx factory start hello --input '{"task": "add a CONTRIBUTING.md"}' --watch

--watch streams the run’s events until it finishes and exits non-zero if it failed, so it drops straight into a script or a CI job.

The run clones a fresh working tree, hands it to the agent, runs whatever your workflow runs, and pushes a branch and opens a PR if the workflow calls ctx.writeBack. You can watch all of it in the browser while it happens.

Next

• Writing workflows — the shape of defineWorkflow and the ctx you get.
• Configuration — every key in factory.config.ts.