Factory

Turn GitHub issues into tested pull requests with local coding agents.

Describe what you want to build in a GitHub issue—an Objective. Factory breaks it into smaller tasks called Work Items, tracks their dependencies, runs ready tasks in parallel, validates their results, and integrates accepted changes. You direct the work through Codex chat; GitHub holds the issues, dependencies, pull requests, and execution records.

Built for indie developers and small teams, Factory runs on your Linux computer. A local controller keeps work moving while it is running and recovers progress from GitHub after a restart. No Factory GitHub Actions workflow, hosted service, or database is required.

Important

Development preview. The plugin currently installs from reviewed repository snapshots on main, not a published release tag. Manifest versions identify development builds; older Git tags do not identify the current plugin. The npm CLI/controller is not yet a verified published install path. Record your installed commit/version and read the release qualification before authorizing unattended work.

Install and activate

Start in Linux, Windows WSL2, or a Linux guest on macOS with Node.js 20+, Git, GitHub CLI, and Codex CLI. The installation procedure is verified with Codex CLI 0.153.0; newer clients must expose the same plugin commands. Keep your target checkout and credentials inside the Linux environment.

For the portable prompt layer, install Factory's three public skills directly from this repository:

npx skills add clockgrove/factory

The Skills CLI finds director, factory-setup, and objective-compilation and lets you select the agents and project or global scope. This is an ordinary third-party skill installation. It does not register the current repository with Factory, install a controller, or start work. Skills alone do not supply Factory's MCP execution tools.

For Codex execution, install the full plugin instead of keeping a second copy of the same skills:

1. Install the plugin, which bundles those skills and Factory's MCP server:

   codex plugin marketplace add clockgrove/factory --ref main
   codex plugin add factory@clockgrove-factory
   codex plugin list
   

2. Authenticate in the same Linux user/process environment:

   codex login
   gh auth login
   

3. Fully restart Codex to load Factory's skills and bundled MCP server. Open your target repository's checkout and ask:

   Use Factory to inspect this repository for existing Objectives and prerequisites. Do not start work.

Factory performs bounded read-only discovery when the repository is known but the Objective number is not. A complete result with one candidate selects it; ambiguous or incomplete results ask you to choose. Inspection checks repository identity, access, branch rules, local runners, validation tools, and resource headroom. Success means the plugin loads, an authenticated local backend is available, and the selected Objective and checkout are accessible. Inspection does not start workers. When ready, ask in ordinary language—for example, “Use Factory to build this repository; reuse its existing Objective.” Factory maps that execution request to its internal activation and compilation operations.

The full plugin bundles Factory's runtime; a separate Skills CLI install and a sandbox account are not needed for this path. Local workers use the Codex SDK by default, with Codex CLI fallback. Local-only work still consumes your model account's quota. Follow the local quick start for permissions, activation, troubleshooting, and the source-checkout CLI path.

Plugin installation is global and has no destination-repository argument, so it does not add files to the repository you have open. To give human authors a guided Objective form, open the chosen checkout after restarting Codex and ask:

Add Factory's shipped human Objective issue form to this repository. Preserve its existing issue templates and make the form an ordinary reviewable repository change.

Factory ships the canonical form for that explicit request. You can also review and copy it manually to .github/ISSUE_TEMPLATE/objective.yml. It is optional and does not change Factory's activation or execution authority.

Try a small Objective

In a trusted Node.js repository with committed npm metadata, a lockfile, and a working npm test, create an issue like this:

## Outcome
Add a `healthcheck` npm script that runs the existing fast test command.

## Acceptance
- `npm run healthcheck` exits successfully from a clean checkout.
- Existing tests still pass.
- Change only package metadata and a focused regression test if needed.

## Boundaries
Use the existing Node/npm toolchain. Do not add dependencies, services,
secrets, network access, generated files, deployment, or release work.

Keep the Objective: title prefix used by the canonical form. You can use the inspection prompt above without knowing the issue number. After an execution request, Factory compiles a missing Work Item graph automatically, runs workers, independently validates their artifacts, and delivers tested changes through pull requests. The run ends with a terminal status and recorded usage, or a specific escalation explaining what needs your attention. See the first-Objective walkthrough for expected evidence.

When opt-in compiler evaluation uses maxRepairs, that number is one shared correction budget for obligation-inventory regeneration and graph repair. For example, one inventory correction under maxRepairs: 2 leaves at most one graph correction. Report-only evaluation and maxRepairs: 0 keep the inventory single-shot; invocation, time, observed-token, accounting, and input fences still apply before every model call. Exact usage alone never authorizes an inventory retry: only a retained, bounded response that fails deterministic claims schema or evidence-grounding validation is repairable.

For local compiler debugging, set FACTORY_MANAGEMENT_TRANSCRIPT_DIR to an absolute Linux path before launching Factory or installing its unattended controller. Factory then writes private, bounded JSON records containing the exact prompt and schema it supplied, every assistant message and provider event visible through the Codex CLI boundary, timing, outcome, and the input/output/cached token split. Provider-owned system and developer messages are recorded as unavailable because Codex CLI does not expose them. These files stay on the host and never become GitHub evidence or recovery state. See local management transcripts.

What Factory handles

• Planning and scheduling: acceptance criteria, native GitHub dependencies, ready-task ordering, and local CPU/memory admission. The default ceiling is two workers; adaptive concurrency is opt-in.
• Execution and delivery: isolated Git worktrees, independent validation, ordinary pull requests, and explicitly selected native stacks with capability checks.
• Recovery and inspection: durable GitHub records, restart recovery, cancellation, status, explanations, and replay without a separate database.
• Optional execution routes: durable local Codex App Server sessions, Daytona cloud burst, and limited GitHub-managed integrations, subject to each provider's supported capabilities.

Factory executes on Linux. Native Windows/macOS execution, coordinating multiple local computers, and a custom UI are outside the current scope. Vercel Sandbox is a Labs adapter. Supported behavior and live qualification are distinct; consult the operating scope and release qualification.

Safety and escalation

Use local workers only with trusted code: a same-user local process is not a hardened confidentiality boundary. Workers use workspace-write; web search and command networking are off by default. Factory checks repository identity, permissions, branch rules, scope, artifact evidence, and budget, and escalates when it cannot safely proceed. Retries do not widen permissions, scope, or spending.

Paid cloud execution requires explicit authorization and resource limits. Model-token budgets stop before a subsequent call using observed usage; concurrent calls can overshoot them. Resource-minute and session limits are not guaranteed dollar caps. You own provider billing and provider-side limits; unavailable usage is never counted as zero. Read the full policy and threat model before unattended execution.

Documentation

Development

Contributions are welcome. Start with the contributor guide for setup, focused checks, and review expectations. The coordinated release gate is:

npm ci
npm run verify:release

It requires supported Linux, systemd 254+, and a reachable systemd user manager. See the release verification procedure for exact prerequisites and remaining external gates.

Factory is MIT licensed. For questions and bug reports, use support. Report vulnerabilities through the security policy. Community participation follows the code of conduct and governance.