fabrika is a set of tools for building your own software factory: a pipeline that takes a ticket
to a merged pull request, where code runs the steps and agents only do the writing. It is built
on @demlik/tea, the Elm architecture in TypeScript.
- It is an experiment. Some parts are proven on real tickets. Others are still drafts.
- You get it by cloning this repository. The package,
@kampus/fabrika-old, is not on npm yet. It is marked"private": trueand has no license yet. - It is for TypeScript developers who want to run, study or build an agent pipeline, and for the people working on this one.
Five parts, from the bottom up:
- Programs. A program is a thing you start: a name, typed flags, typed inputs and outputs,
and a
mainthat runs tea state machines. - A host. A host is a process that runs programs. It runs each program under a name, on one
ledger.
- The ledger is a shared, durable record: every program's state and messages live there.
- A host holds a lease on a name: a hold that runs out unless renewed. If the host dies, another host takes the name over and replays from the ledger.
- This is Erlang/OTP's idea of a node, for tea programs.
- A shell, tsh. A Unix-style shell that runs only tea programs. Pipes are typed:
seq | upperis refused before it starts, because numbers do not fit an input of text. - Agents. An agent run is one step inside a program, with a budget in dollars. It runs Claude through the Agent SDK, or any harness (a tool that runs an agent, like Claude Code) that speaks the Agent Client Protocol.
- The work pipeline. Programs for each step of the work, where a stage is one step:
plan, build, review and ship. A quest is one plan's whole path, from ticket to merged pull
request; today's code calls it a
lane. It is an app built on the tools above, in its own package,@kampus/pipeline. That name is a placeholder: the pipeline's own name is still open.
- Code holds the loop. Which step is next, what to wait for, when to stop and when to ask a person: code decides all of that. An agent does one bounded job inside it, such as writing code or review findings. See Control lives in code.
- Code is cheap, fast, testable and the same every time. An agent is none of those. So every fixed step moves out of agent prose and into a state machine.
- Every outside thing sits behind a typed service. The ledger, GitHub and the agent harness are each a service, so a test swaps in a fake and no step calls a command-line tool directly. See The backend is a library.
- Nobody grades their own work. The reviewer is a different agent from the builder, and no agent approves a pull request. See Nobody grades their own work.
Every decision has a short note in docs/direction/.
You need Node 26 (the repository pins 26.13.0), pnpm 12 and git. Nothing here needs an API key
or spends money. Run it with TYPESAFE_API_KEY unset.
-
Clone this repository, open its folder, and install:
pnpm install
-
List the programs tsh knows:
bin/tsh -c 'programs'tsh first prints where it read its settings from, and one line per setting it picked. With no
.fabrika/fabrika.tomlevery pick is a default:.fabrika/fabrika.toml: <this folder>/.fabrika/fabrika.toml, not there: every default agents.plan: opus (default), effort medium (default), at most $2 a run (default) ... ledger.at: local (default) say Says a text once, and ends. tsh's echo. seq Counts from 1 up to a number, one value at a time, and ends. double Doubles each number it is told, and ends when its input closes. ... -
Pipe two programs together:
bin/tsh -c 'seq --to 3 | double'double 2 double 4 double 6 -
Pipe two that do not fit. Nothing starts:
bin/tsh -c 'seq --to 3 | upper'tsh: does not fit: seq's outputs (n: integer) fit no input of upper (text: string). Nothing was started seq --to 3 | upper ^ -
Look at the owner's desk, the inbox of everything that waits on a person. This one is a demo, kept in memory:
bin/tsh -c 'desk-demo'It lists ten asks: plans to approve, a stuck task, and questions to rule on.
bin/tsh with no arguments opens an interactive prompt. tsh keeps its history, its job storage
and its local ledger in ~/.tsh (set TSH_HOME to move it).
This is an older path, not the current way. To run a ticket today, use
Run a ticket through the pipeline. This section stays until
deliver is deleted.
It is wired, but it has not yet taken a real ticket to a merged pull request. Experiment 105 ran the same quest against a fake GitHub. Read experiment 105 before you try it.
- It writes to the repository you name. It pushes a branch and commits, and opens one pull request per plan.
- It spends money. By default each agent run may cost up to $2, and one step of the quest, with its retries, up to $20.
Steps:
-
Make sure these work in your shell:
ghis logged in, with write access to the target repository.- Claude is logged in for the Agent SDK: the system keychain,
CLAUDE_CODE_OAUTH_TOKENorANTHROPIC_API_KEY. git pushto that repository works from this machine. fabrika clones it over https.
-
Make a folder for the target inside this clone.
runs/is ignored by git:mkdir -p runs/widgets && cd runs/widgets
-
Write a
tsh.tomlthere that names the repository:repo = "acme/widgets"
Every other key has a default. The keys are listed at the top of
packages/pipeline/src/tsh/config.ts. -
In the target repository, commit a
.fabrika/fabrika.tomlon its default branch. Its keys (agent models, install, checks, approval) are listed at the top ofpackages/pipeline/src/settings.ts. See also One fabrika.toml per repo. -
Start tsh from that folder, and read its first lines:
../../bin/tsh
- tsh clones the repository under its home (
~/.tsh/work/) and reads.fabrika/fabrika.tomlfrom its default branch, as committed. - Each pick is printed with why. Fix any line that warns you, for example a missing
.github/CODEOWNERS, which stops ship atapproval_unknown. programsnow lists three more:review,plananddeliver.deliveris listed only when each review has a check to run: the install that the repository's lockfile names, or a[[checks.run]]in its.fabrika/fabrika.toml.
- tsh clones the repository under its home (
-
Look before you run. These only read:
deliver --help ship --mode read pr=https://github.com/acme/widgets/pull/12 -
Deliver one ticket, in the background, and answer the desk:
deliver plan=https://github.com/acme/widgets/issues/42 & desk answer --ask plan:acme/widgets#42@1 --reply /approvedeliverplans the ticket, then waits for you to approve the plan on the desk.- Once approved, it builds each task on one branch, reviews it, opens one pull request and ships it under the repository's own merge rules.
- Killed or crashed, run the same line again. It goes on from where the quest stood.
- Only one tsh may use a home at a time, so run
deskandanswerin the same tsh.
These still run, but they are not the way forward:
operate ticket=<url>in tsh: the older one-ticket loop (build, review, ship). It is going to be deleted. Use the pipeline.- The first-generation factory (
pnpm demo,pnpm real) is gone from main. It stays in git at the tagarchive/2026-11-09.
| You want to | Go to |
|---|---|
| Know what is next, and who has the move | docs/plan/ |
| Run a ticket through the pipeline | docs/how-to/run-a-pipeline-ticket.md |
Write code with @kampus/fabrika-old |
packages/fabrika/README.md |
| Change the work pipeline | packages/pipeline/README.md |
Write a program for next/ |
docs/how-to/write-a-next-program.md |
| Learn today's host by doing it | Tutorial: Two hosts, one ledger, then Agents on two hosts |
| Know why a choice was made | docs/direction/ |
| See what was tried, and what came back | experiments/ |
| See what happened on real tickets | field/ |
A pnpm workspace. A package may import the ones listed before it, never the ones after.
layer-rules.json holds the order, and pnpm lint checks it.
packages/fabrika,@kampus/fabrika-old: the tools, in one package. It names no pipeline. Its parts, bottom first:packages/pipeline,@kampus/pipeline(a placeholder name): the work pipeline, an app on fabrika's public names. The stages, the services they use, the programs it lists in tsh, and thetshthat lists them.packages/ledger-server,@kampus/ledger-server: one shared ledger on Cloudflare for a team, declared with Alchemy, and its twin on the laptop from the same Worker.programs/: one package per program that runs on its own.programs/counter,@tea-fabrika/counter: the smallest program with a window. It counts presses of +1 until done.programs/tracker,@tea-fabrika/tracker: tickets on the ledger, one stream of facts each, and a window to work them.programs/experiments,programs/experimentandprograms/compare: experiments on the ledger, the list, one page, and two runs side by side (experiment 170).programs/markdown,@tea-fabrika/markdown: draws any markdown it is told, in a window, asgloworlessdoes.
apps/: what a person opens, on top of everything else. Nothing imports an app.apps/fabrika,@kampus/fabrika-app-old: the fabrika app, a walking skeleton. One window, tiled like tmux; every tile runs its own tsh, with a line editor, and a program with a view runs inside a tile.
docs/tutorials/: tutorials, with their finished files type-checked.docs/: drafts too:review-machine.mdandship-machine.md.fixtures/: toy projects the tests use.
Read AGENTS.md before you change anything. It says where each kind of note
goes, how to write here, and the rules for a live run.
Run the formatter first, then the three checks. All three must pass before you push. None needs a key or the network.
pnpm format # formats and sorts imports, in place
pnpm typecheck
pnpm lint # fails on a warning too
pnpm testOther commands:
| What | Command |
|---|---|
Build the dist/ of @kampus/fabrika-old and @kampus/pipeline (nothing in the repo needs it) |
pnpm build |
tsh, the same as bin/tsh but without its check for missing packages |
pnpm tsh |
| tsh with only its small programs (fabrika installs no command) | packages/fabrika/bin/tsh-small |
Open the fabrika app: tsh in a window, with the small programs, counter and tracker |
pnpm fabrika |