factory

A self-evolving, stateful, decomposed meta-harness. Describe what you want — re:factory builds it, tests it, and keeps improving it, autonomously. A CEO agent orchestrates eight specialists that observe, hypothesize, build, review, measure, and learn from every experiment. Runs with Claude Code, Bob Shell, and OpenAI Codex.

All state is local — per-project in .factory/ (add to .gitignore), global in ~/.factory/. See Architecture for the full deep-dive.

---

Quick Start

Prerequisites: Python 3.11+, uv, and Claude Code (installed and authenticated).

git clone https://github.com/akashgit/remote-factory.git
cd remote-factory
uv sync

Then just run:

uv run factory

The welcome wizard launches automatically — a conversational agent that asks what you want to do, classifies your input (an idea, a file path, a GitHub URL, or a description), and presents the right command. No flags to memorize. Paste an idea and the wizard handles the rest.

You can also skip the wizard and call commands directly:

uv run factory ceo "Build a personal homepage with a blog" --mode design

See the full setup guide for authentication and environment variables.

---

What Do You Want to Do?

I want to…	Command
Start from a raw idea	uv run factory ceo "my idea" --mode design
Build from a spec or repo	uv run factory ceo spec.md
Improve an existing project	uv run factory ceo /path/to/project
Fix or add one thing	uv run factory ceo /path --focus "add dark mode"
Target a GitHub issue	uv run factory ceo /path --focus 42
Contribute to an upstream repo	uv run factory ceo https://github.com/user/repo --clean-pr
Optimize a metric (research)	uv run factory ceo "build a harness to solve HMMT Feb 2026 C7" --mode research

---

Design Workflow

Use design mode when you want to brainstorm before building. Start a conversation with the CEO to refine an idea, then build:

# From a raw idea — discuss and refine into a buildable spec
uv run factory ceo "distributed task runner" --mode design

# From a spec file — read and discuss before building
uv run factory ceo ~/ideas/my-app-spec.md --mode design

Design mode also works on existing projects. The CEO studies the backlog, eval scores, open issues, and experiment history, then discusses what to work on before executing:

uv run factory ceo ~/factory-projects/my-app --mode design

# Seed the conversation with a topic
uv run factory ceo ~/factory-projects/my-app --mode design --focus "auth layer"

---

Build Workflow

When you already have a spec file, a GitHub repo, or a clear description, re:factory builds directly — no design step needed:

uv run factory ceo ~/ideas/spec.md
uv run factory ceo https://github.com/user/repo
uv run factory ceo "Build a personal homepage with a blog"

The pipeline: Researcher surveys best practices → Strategist creates a plan → Builder implements and commits → E2E gate confirms it runs. Override the output directory with --dir my-site. (If you start with a raw idea via --mode design, the CEO refines it into a spec first, then transitions into this same build pipeline automatically. --mode interactive remains accepted as an alias.)

After the first build, a backlog appears at .factory/strategy/backlog.md — deferred features that feed future improvement cycles. Manage it with uv run factory backlog-list, uv run factory backlog-add, and uv run factory backlog-remove.

---

Improve + Focus Workflow

Point re:factory at an existing project and it enters Improve mode automatically:

uv run factory ceo ~/factory-projects/my-app