cat-factory

Plan software work on a visual board, and let LLM agents deliver it as reviewed, CI-green pull requests while your team keeps the decisions.

Website & docs · Introduction · First task tutorial · Cookbook · MIT license

cat-factory is a self-hosted platform for running software delivery with agents. You lay out your services and the tasks inside them on a board, or pull tasks in from Jira, Linear, GitHub or GitLab. For each task, an agent pipeline does the work: it settles the requirements with you, writes the code on a real checkout of your repository, reviews and tests it, and opens a pull request that waits for green CI and your merge policy. You watch every step live and step in wherever a person should decide.

It runs on your own infrastructure (your laptop, a Node.js server, Kubernetes or Cloudflare) with the model providers you choose.

• How a task becomes a pull request
• Try it locally
• Where to go next
• What you get
• How it works
• Deployment
• Repository layout
• Working on cat-factory itself

1. Describe the work. Put a task on the board inside the service it belongs to, or let a connected tracker file it the moment an issue is created.
2. Settle the requirements. A reviewer agent points out gaps, risks and open questions; you answer them, and the answers are folded back into the task.
3. Build it. A coding agent clones the linked repository in an isolated container, implements the change, and runs the service's own lint, test and build checks before anything is pushed.
4. Verify it. Reviewers, testers and (if you want them) multi-model review panels and rubric judges check the work and send it back when it falls short.
5. Merge it. The pull request carries a briefing written by the agent that did the work, plus a verification report. It merges once CI is green and your merge policy allows it, either automatically or after a person approves.

Along the way you choose which model runs each step, which steps need a human sign-off, and how much the organisation may spend per month. When a run needs you, the board says so.

You need Node 24 or newer and a container runtime (Docker, Podman, OrbStack, Colima or Apple container). One command scaffolds a local deployment in a new directory:

npx @cat-factory/cli init

It asks a few questions (project name, whether agents run in Docker or through your own installed claude/codex CLI, GitHub or GitLab), generates the secrets the server needs, and helps you mint a source-control token. Then start the two halves, each in its own terminal:

cd <project>/local    && npm install && npm run db:up && npm start   # backend on :8787
cd <project>/frontend && npm install && npm run dev                  # app on :3000

The first backend start takes a minute while it pulls the image agents run in. Open http://localhost:3000, add a model provider (Cloudflare Workers AI is the quickest; any vendor API key works), connect a repository, and start your first task. The first task tutorial walks through that run step by step.

More detail: Run locally on the website, and the @cat-factory/cli reference for every flag and subcommand.

The product documentation lives on catfactory.ai. This repository documents how cat-factory is built.

A short tour. Every capability is described in full in docs/capabilities.md.

• A board that is the plan. Services, modules and tasks on a zoomable canvas, with dependency edges and tasks sorted into status lanes. Point cat-factory at an existing repository and it maps the codebase onto the board for you.
• Agent pipelines you can shape. Reusable chains of steps (architect, coder, reviewer, tester and more), a ladder of ready-made presets, per-step model choice, editable agent prompts, and expensive steps that skip themselves on small tasks.
• Real code, verified before you see it. Agents work on a real checkout, run your checks before opening a pull request, and back each change with a verification report that pairs every requirement with its evidence.
• Review that scales. Deep review of large pull requests, multi-model consensus panels, and rubric judges that send weak work back to the agent that produced it.
• Humans hold the levers. Decision prompts, step gates with named approvers, merge rules per kind of change and per role, and an audit log of who did what.
• Bug work, end to end. Hunt a codebase for unreported defects, rank a tracker's open bugs by impact against effort, and prove a fix with a test that fails before it and passes after.
• Test environments on demand. Per-pull-request preview environments on Kubernetes, Cloudflare or your own tooling, for the agents that deploy and test.
• Connected to your tools. GitHub and GitLab, Jira, Linear, Confluence, Notion and Figma, plus Slack, email and webhook notifications.
• Spend under control. An organisation-wide monthly budget with forecasts and alerts; runs pause at the cap instead of overrunning it.
• Observable to the last token. Every step, model call and tool call is recorded, with failure-first triage, spend reports and OpenTelemetry or Langfuse export.
• Built to be extended. A deployment adds its own agent kinds, gates, judges, tool servers (MCP), model providers, runner pools and UI modules in its own code, without forking.
• Headless when you need it. A stable /api/v1 with official TypeScript, Python, Go and Java clients, and an MCP server.

flowchart TB
    SPA["<b>Nuxt SPA</b> · frontend/app<br/>Vue Flow board"]

    subgraph neutral["Runtime-neutral backend (the same code on every target)"]
        HTTP["<b>HTTP layer</b> · @cat-factory/server<br/>Hono controllers, auth, RBAC"]
        DOMAIN["<b>Domain</b> · orchestration, integrations, agents<br/>the delivery engine and its registries"]
        PORTS["<b>Ports</b> · @cat-factory/kernel<br/>repositories, durable execution, events, VCS, models"]
        HTTP --> DOMAIN --> PORTS
    end

    subgraph facades["Runtime facades (one per deployment target: adapters only)"]
        CF["<b>Cloudflare Worker</b><br/>D1 · Workflows · Durable Objects · Containers"]
        NODE["<b>Node service</b><br/>Postgres/Drizzle · pg-boss · realtime hub · runner pool"]
        LOCAL["<b>Local</b><br/>the Node stack, containers on your machine"]
    end

    JOB["<b>Per-run container</b><br/>executor-harness drives a coding agent<br/>on a real checkout"]
    VCS[("GitHub / GitLab<br/>branch, PR, CI, merge")]

    SPA -- "REST" --> HTTP
    HTTP -. "events PUSHED over WebSocket, never polled" .-> SPA
    PORTS --> CF & NODE & LOCAL
    CF & NODE & LOCAL -- "dispatch" --> JOB
    JOB -- "clone, implement, push" --> VCS
    JOB -- "progress, telemetry" --> PORTS

A run is durable: the server advances it one checkpointed step at a time, so it keeps going whether or not a browser is open and survives restarts. The long agent work happens in a container, and every state change is pushed to the board as it happens.

Everything above the facade line is the same code on every deployment target. Each facade supplies only the storage, job queue and container adapters for its platform, and a shared conformance suite runs the same assertions against all of them.

Deeper reading: Architecture on the website, the backend overview, and the flow index for each runtime flow in turn.

cat-factory ships as libraries on npm plus a runner image on GHCR and Docker Hub. A deployment is a small project of its own that depends on those packages and carries its own configuration and secrets. The deploy/* directories here are templates to copy: every id and hostname in them is a placeholder, and this repository operates no deployment of its own.

Every target also needs a source-control connection (GitHub App or a GitLab token) and sign-in (configuration, enterprise SSO). Every environment variable is listed in Environment variables.

Already running a Kubernetes cluster? Agent jobs and per-pull-request preview environments can run on it, whichever target hosts the backend: Kubernetes.

One pnpm workspace. The short map:

Every package, its role and where it is published: docs/repository-layout.md.

Everything above is about using the platform. This part is for changing it.

• CONTRIBUTING.md: setting up the workspace, the common commands, and the changeset every PR needs.
• AGENTS.md: the rules every change is held to (runtime symmetry, size ratchets, compatibility, logging and more). It is also what orients a coding agent, and each package carries its own AGENTS.md with a "where things live" map.
• docs/README.md: the map of this repository's docs, including the feature guide that pairs each capability with its website page and its design doc.
• docs/glossary.md: the code-level naming map (block vs task vs card, directory vs package names). The product vocabulary is the website's Glossary.
• Running the tests: the Postgres the Node and local suites need, and the traps that make a working tree look broken without one.