factory
A reference software factory for Claude Code and Codex
What is it?
What it is
A reference software factory that installs a repeatable operating model into GitHub projects, using stock Claude Code or Codex to triage issues, implement bounded work, run deterministic gates, and open draft pull requests under human oversight.
Why it exists
To automate mechanical software delivery loops while keeping engineering judgment with humans, enabling version-controlled agent workflows without a custom orchestrator, and using GitHub Issues as a durable work queue.
Who should use it
Engineering leads building AI-assisted delivery pipelines on existing GitHub repositoriesTeams running Claude Code or Codex who want unattended agents to handle bounded, charter-permitted tasks under human reviewSolo developers or small teams who want a repeatable triage-to-PR loop with explicit human gatesOrganizations evaluating software-factory patterns who need a reference implementation that uses stock Claude Code and Codex rather than a custom orchestrator
Who should avoid it
Beginners who have never used Claude Code, Codex, or GitHub Actions and expect a turnkey one-click setupTeams unwilling to write or maintain a human-owned charter that defines tier, load-bearing paths, and stop conditionsProjects where every change is ambiguous, load-bearing, or requires deep product judgment with no scoped, automatable workAnyone who wants agents to autonomously merge pull requests or operate without GitHub branch protection as the final enforcement boundaryRepositories that cannot be installed into (no GitHub remote, no test/lint/build commands, or no willingness to add `.claude/` and `docs/factory/` directories)
How it works
A quick walkthrough in plain English
How factory works
Step 1 of 3
You interact with it
Open factory, send a request, or connect it to your stack.
Features
Advantages
- Automates repetitive mechanical steering while preserving engineering judgment
- No custom orchestrator or queue service – uses stock Claude Code and GitHub native features
- Deterministic, restartable loops with evidence stored in the repository
- Clear handoff protocol (`factory-handoff:v1`) between independent runs
- Human‑controlled merge gate – no automated merges, enforced by branch protection
- Version‑controlled policies (CHARTER, CONTRACT, skills, gates) that drive terminal, Desktop, cloud, and routines
- Back‑pressure control via `STOP_IF` limits review queue size, preventing overload
- Separate verifier that grades evidence independently of the implementation run
- Live visibility via `/factory` and `/factory-tune` for tuning and monitoring
- Idempotent installer – safe to re‑run, never overwrites existing files
Disadvantages
- No native GitHub `issues` trigger; relies on scheduled triage or optional Action
- Requires a scheduled routine (or custom Action) to poll for new issues
- Merge is never automated – must be done manually, adding a step to the workflow
- Environment and cloud config cannot be committed; must be documented externally
- A “green” run only means the session exited without infrastructure error, not that the work succeeded
- The factory is a reference installer – you must adapt it to your own repo and charter
- Human review remains the bottleneck; the system cannot scale past your decision capacity
- Branch‑protection hooks guard against accidental merges but are not a complete security boundary
Installation
cloud
The factory integrates with cloud services (Claude Code cloud routines) for scheduling and compute. After running the native installer (`install.sh`), the cloud routines are automatically available for triage, implementation, verification, and monitoring. There is no separate cloud installation step—the cloud capability is bundled with the local installation via the `install.sh` script.
native
Clone the repository, then run the installer script: ```bash git clone https://github.com/addyosmani/factory.git cd /path/to/your/repo /path/to/factory/install.sh --dry-run . /path/to/factory/install.sh . ``` The installer never overwrites existing files, so re-running is safe. Cloud routines (Claude Code cloud routines) provide the default clock and compute. All sessions start from a fresh clone of the repo; the cloud environment is established during the initial installation.
FAQ
What is the purpose of the Factory repository?
It provides a repeatable, version‑controlled operating model that turns GitHub Issues into a work queue and automates triage, implementation, verification, and PR creation using Claude Code or Codex, while keeping engineering judgment with a human.
How does a GitHub issue become a reviewed pull request?
The scheduled triage routine assigns a `factory:*` label, a later implementation run claims a deterministic branch, runs gates and a fresh verifier, opens a draft PR, and a verification routine checks the PR before the human decides to merge or revise.
What role does the human play in the Factory workflow?
The human defines the charter and tiered risk budget, approves product intent and design, reviews PRs, merges changes, and ensures that any work touching load‑bearing code or existing tests receives final approval; agents may not merge or approve their own work.
How do I install the Factory into my project?
Clone the repository, run `install.sh` against your target repo (e.g., `./install.sh .`), then follow the steps in GETTING_STARTED.md; the installer never overwrites existing files, so re‑running is safe.
What are the key limitations I should be aware of before using the Factory?
There is no native GitHub `issues` trigger (triage polls hourly or via an optional Action), green run status does not guarantee success, environment variables cannot be committed, and merge is never automated—GitHub branch protection remains the final enforcement.
Featured in Videos
YouTube tutorials and walkthroughs for factory
Alternatives
Similar projects ranked by category, topics, and text overlap.
