factory

The Factory: From Idea to Evolving Software

Describe what you want. The Factory builds it, tests it, and keeps improving it — autonomously. You give it a spec file, a rough idea, or an existing codebase. The Factory researches best practices, scaffolds the project, sets up evaluation, and runs a continuous improvement loop — measuring every change and keeping only what makes things better.

---

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

That's it. You're ready to go. Every command runs from the factory repo directory — you pass the target project as an argument.

# Option A: run directly (no install needed)
uv run python -m factory ceo "Build a personal homepage with a blog"

# Option B: install as a CLI tool, then use `factory` anywhere
uv tool install -e .
factory ceo "Build a personal homepage with a blog"

Both forms are equivalent. This README uses uv run python -m factory throughout so you can copy-paste without installing first. If you've installed the CLI, just replace uv run python -m factory with factory.

The factory stores all state locally — no external services required beyond Claude Code. Per-project state lives in .factory/ (add it to .gitignore). Global state (project registry, evolved playbooks) lives in ~/.factory/.

See the full setup guide for authentication, environment variables, and tmux configuration.

---

Architecture

A CEO agent orchestrates eight specialists — Researcher, Strategist, Builder, Reviewer, Evaluator, Archivist, Distiller, and Failure Analyst — each running as an independent Claude Code subprocess.

The Python CLI provides measurement and storage tools (Layer 1). The CEO agent makes all workflow decisions (Layer 2). Specialist agents execute narrow tasks (Layer 3). See Architecture for the full technical deep-dive.

The CEO detects your project's state and routes to the right mode automatically:

---

Walkthrough: Build → Improve → Steer

Here's a complete workflow — from a one-line idea to a continuously improving project.

Step 1: Build from an idea

uv run python -m factory ceo "Build a personal homepage with a blog and projects section"

The Factory creates a project directory at ~/factory-projects/build-a-personal-homepage-..., initializes a git repo, and launches Build mode. Here's what happens:

1. The Researcher surveys similar projects, tech stacks, and architecture patterns
2. The Strategist creates a phased implementation plan (scaffold first, then features)
3. The Builder implements each phase, committing code and opening PRs
4. An E2E verification gate confirms the project actually runs end-to-end

The input is flexible — a raw string, a spec file (~/ideas/spec.md), or a GitHub URL (https://github.com/user/repo) all work.

Step 2: The backlog appears

After the first build, the Factory creates a backlog — .factory/strategy/backlog.md. This is a work queue that feeds all future improvement. It contains:

• Features deferred during build (things that need API keys, external services, or manual setup)
• Everything that could be built was built — only human-blocked items remain

# Check what's in the backlog
uv run python -m factory backlog-list ~/factory-projects/build-a-personal-homepage-...

Step 3: Improve it

Point the factory at the project again. It detects the existing .factory/ directory and enters Improve mode:

uv run python -m factory ceo ~/factory-projects/build-a-personal-homepage-...

Each improvement cycle: