Skip to content

About

An agent factory where Claude Code and Codex do the work, Effect and tea do the bossing around, and every decision, mistake and 3am rabbit hole gets written down because apparently we’re scientists now. lol. — Claude

Resources

Code of conduct

Stars

7 stars

Watchers

0 watching

Forks

Latest commit

 

History

2,234 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

tea-fabrika

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": true and 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.

What fabrika is

Five parts, from the bottom up:

  • Programs. A program is a thing you start: a name, typed flags, typed inputs and outputs, and a main that 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 | upper is 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.

Why it is built this way

  • 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/.

Try it in two minutes

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.

  1. Clone this repository, open its folder, and install:

    pnpm install
  2. 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.toml every 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.
    ...
    
  3. Pipe two programs together:

    bin/tsh -c 'seq --to 3 | double'
    double 2
    double 4
    double 6
    
  4. 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
                 ^
    
  5. 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).

Use it on a real repository

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:

  1. Make sure these work in your shell:

    • gh is logged in, with write access to the target repository.
    • Claude is logged in for the Agent SDK: the system keychain, CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.
    • git push to that repository works from this machine. fabrika clones it over https.
  2. Make a folder for the target inside this clone. runs/ is ignored by git:

    mkdir -p runs/widgets && cd runs/widgets
  3. Write a tsh.toml there 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.

  4. In the target repository, commit a .fabrika/fabrika.toml on its default branch. Its keys (agent models, install, checks, approval) are listed at the top of packages/pipeline/src/settings.ts. See also One fabrika.toml per repo.

  5. 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.toml from 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 at approval_unknown.
    • programs now lists three more: review, plan and deliver.
    • deliver is 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.
  6. Look before you run. These only read:

    deliver --help
    ship --mode read pr=https://github.com/acme/widgets/pull/12
  7. 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 /approve
    • deliver plans 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 desk and answer in the same tsh.

Older paths, kept for now

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 tag archive/2026-11-09.

Where to go next

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/

What is in this repository

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:
    • program: programs.
    • host: the host and the ledger.
    • shell: tsh, with its small programs only.
    • agents: agent runs (Claude through the Agent SDK, any harness over ACP), their sandbox and their traces.
  • 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 the tsh that 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.
  • 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.md and ship-machine.md.
  • fixtures/: toy projects the tests use.

Working on this repository

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 test

Other 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

About

An agent factory where Claude Code and Codex do the work, Effect and tea do the bossing around, and every decision, mistake and 3am rabbit hole gets written down because apparently we’re scientists now. lol. — Claude

Resources

Code of conduct

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages