⚙ GitFactory

Factorio-style factory builder for GitHub automation: blueprints compile to Actions workflows running Claude Code.

A Factorio-style factory builder for GitHub automation. (working title)

Drag machines onto a canvas. Connect them with belts. Hit Deploy — and your blueprint compiles into real GitHub Actions workflows where Claude Code agents triage issues, review PRs, garden stale threads, and commit fixes on your actual repositories.

 [📥 Issue opened] ══▶ [⚙ Claude: triage] ══▶ [🏷 Apply labels]
                                          ╚══▶ [📝 Post summary comment]

 [⏰ Nightly 03:00] ══▶ [⚙ Claude: gardener] ══▶ [📝 Stale-issue nudges]

No servers. The frontend is a static site; GitHub is the database, the event bus, and the compute layer. Blueprints live in your repo, prompts live in your repo, telemetry is read back from the Actions API and rendered as factory floor status.

• Drag-and-drop factory canvas: machines are triggers, Claude Code agents and actions, connected by belts
• Deploy compiles a blueprint into readable GitHub Actions workflows in your repo
• Blueprints and prompts are versioned in the repo and shareable as encoded strings
• Factory-floor status rendered from the Actions API
• A static frontend with no servers: GitHub is the database, event bus and compute

• Blueprint-in-repo — your automation design is versioned, reviewable, and shareable as an encoded blueprint string, like the game.
• Compile-to-Actions — no bespoke runtime to babysit; the emitted YAML is readable, auditable, and works without GitFactory existing.
• Agents as machines — each Claude agent has a prompt contract, scoped tool grants, loop guards, and telemetry, because an unbounded agent is just a fire.

The app is built on tt-a1i/archify's design language and viewer model — "The Evidence Console": a dominant canvas, compact chrome, progressive disclosure. Press / to find a machine, click one to open its passport (dials, diagnostics, the tools it will be granted), and flip the Build tab from Floor to Map to see each assembly line drawn as the archify map it compiles to — lanes as roles, the main path, and the bot guard the YAML really carries. Fleet Observe draws any repo's workflows the same way with live run status on every node; the Docs tab embeds the delivered maps; T cycles the theme like the viewer. The delivered HTML maps under app/public/maps/ stay the canonical, exportable artifacts (route probe, presentation, share cards live there) and every surface links to them when one exists for its source.

Agent = Model + Harness. The bamr87 hub (bamr87.github.io/bamr87/harness/) presents and monitors the fleet's harness — a six-layer scorecard and six trip wires computed daily from committed fleet signals. GitFactory is the design side of that loop: the Harness tab renders the hub's page from the same numbers (a pure port of its dash-gen harness, re-run in-app over the hub's committed files with a computed "matches the hub" note), evaluates the same wires live over a Fleet Ops scan, grades a blueprint's design readiness across the six layers (guides, sensors, bounded loop, memory, permissions, observability), and shows every assembly line as the fleet/v1 lane the hub reads — the same card on the floor, in Fleet Observe, and on the tab. The hub is read-only from here; nothing is written to it. ?tab=harness&hub=owner/repo deep-links to another hub, and ?tab=fleet&roster=owner/a,owner/b deep-links to a fleet — the one URL an operator bookmarks to observe, run, cancel, re-run and arm/disarm the loops of exactly those repos (ADR-038). The fleet's content loops live at ?tab=fleet&roster=bamr87/lifehacker.dev,bamr87/irony-works.

Open the app with ?demo=1 and the whole tool comes alive on a fictional three-repo fleet — canvas, prompts, telemetry, and the Fleet Ops cockpit — with no personal access token and no network calls. It is not a mock: the demo swaps in a fixture-backed client behind the same seam a real connection uses, so the compiler and the facts/metrics/audit engines run for real over the fixture data. Nothing is written to GitHub; edits live in the tab until you close it.

All application code lives in app/ (the only npm project); Node 22 is pinned in .nvmrc (nvm use).

cd app
npm install
npm run dev        # vite dev server + HMR → http://localhost:5173
npm test           # vitest — compiler invariant tests
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm run build      # typecheck + production build → app/dist

Open the canvas, drag machines from the palette, connect belts, press Compile to see the generated workflows. The Docker commands below run the same npm scripts inside a container.

No local Node needed — everything runs in a container:

docker compose up dev                       # dev server + HMR → http://localhost:5173
docker compose run --rm dev npm test         # run the vitest suite
docker compose run --rm dev npm run build    # produce app/dist
docker compose --profile preview up --build  # production build via nginx → http://localhost:8080
docker compose down                          # stop everything

Your working tree is mounted into the dev container, so edits hot-reload (VITE_USE_POLLING=true keeps HMR reliable across the macOS ↔ container boundary).

The .vscode/ folder follows the fleet convention (see .vscode/README.md): Terminal → Run Task runs things, F5 debugs them.

• Tasks: Serve (Docker) / Serve (host), Stop, Build, Verify (lint → vitest → build, as CI), Test, Lint, Typecheck, Preview: production (nginx).
• Debug: app in Edge (Docker :5173) — starts the dev server in Docker, then opens Edge with source-mapped breakpoints; the (host :5173) variant uses local Node.
• Debug: Vitest (all) / Debug: Vitest (current file) — breakpoint-debug the test suite.

Four of these directories hold prose. docs/DOCUMENTATION-MAP.md explains the division of labour between them and answers "where does this writing go?".

This repo is designed to be built by Claude Code, session by session, through the spec-driven AO-SDLC loop (docs/AO-SDLC.md):

1. CLAUDE.md — project memory: architecture, golden rules, definition of done.
2. BACKLOG.md → specs/ — pick an item (python3 tools/pick_backlog_item.py) and run /specify → /clarify → /plan → /tasks → /implement, or /evolve for a whole cycle.
3. .claude/commands/ — the chain above plus /add-machine, /compile-check, /session-log.

The bootstrap-era seeds/ (00–07) are kept as history, not as intake.

Powering a deployed factory requires a Claude auth Actions secret on the target repo (the app calls this "connecting power") — CLAUDE_CODE_OAUTH_TOKEN from claude setup-token by default, or ANTHROPIC_API_KEY as the fallback.

Three former repositories now live under packages/, imported with their full history, each keeping its own README, tooling and commands (run from inside the package):

Canvas, compiler, GitHub connect, telemetry, Prompt Studio, the headless-CMS cockpit, Fleet Ops, the archify console, and harness parity with the bamr87 hub — dogfooding itself in .factory/. Pre-alpha; the roadmap is the product spec.

Full commands, conventions and gotchas for humans and AI agents live in CLAUDE.md.

Contributions are welcome via pull request. Use Conventional Commits and keep the CI checks green. See CONTRIBUTING.md for the workflow. AI agents should start with CLAUDE.md.

Notable changes are recorded in CHANGELOG.md; the full record is in the commit history.

Released under the MIT License.

Part of the bamr87 portfolio — browse every project on Amr's GitHub profile.