Describe what you want — re:factory designs and builds it. Brainstorm an idea from scratch, refine a plan for an existing project, or create entirely new factory modes. 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.
A CEO agent orchestrates eight specialists — Researcher, Strategist, Builder, Reviewer, Evaluator, Archivist, Refiner, and Failure Analyst — each running as an independent Claude Code subprocess. The Researcher searches the web and reads prior knowledge from the archive. The Strategist generates ranked hypotheses and handles design-mode ideation. The Builder implements one on an experiment branch. The Evaluator scores before and after. The CEO decides keep or revert. The Archivist records everything to .factory/archive/ and regenerates performance reports for cross-project learning.
The experiment cycle: observe → hypothesize → build → review → measure → decide (keep or revert) → archive. The Strategist picks work from the backlog using FEEC priority (Fix > Exploit > Explore > Combine).
Design mode is the primary way to use re:factory. It researches the space, drafts a structured plan via the Strategist, and lets you iterate on it before any code is written.
From a raw idea — describe what you want and refine it into a buildable spec:
uv run factory ceo "distributed eval runner" --mode design
uv run factory ceo "Build a REST API for bookmark management" --mode designFrom a spec file — read and discuss before building:
uv run factory ceo ~/ideas/weather-dashboard.md --mode design
uv run factory ceo ~/ideas/my-app-spec.md --mode designOn an existing project — study the backlog, eval scores, open issues, and experiment history, then discuss what to work on before executing:
uv run factory ceo ~/factory-projects/my-app --mode designSeed the conversation with a topic — use --focus to start the discussion around a specific area:
uv run factory ceo ~/factory-projects/my-app --mode design --focus "auth layer"
uv run factory ceo ~/my-app --mode design --focus 42 # GitHub issue
uv run factory ceo ~/my-app --mode design --focus "owner/repo#42" # Issue shorthandPrerequisites: Python 3.11+, uv, and Claude Code (installed and authenticated).
uv tool install git+https://github.com/akashgit/remote-factory.gitgit clone https://github.com/akashgit/remote-factory.git
cd remote-factory
uv sync
uv tool install -e .Then start with one of the two main workflows:
# Design — brainstorm an idea, refine it, then build
factory ceo "my idea" --mode design
# Improve an existing project — use design mode with a focus area
factory ceo /path/to/project --mode design --focus "issue # or area to improve"See the full setup guide for authentication, environment variables, and justification for why we install globally.
| I want to… | Command |
|---|---|
| Start from a raw idea | factory ceo "my idea" --mode design |
| Improve an existing project | factory ceo /path/to/project --mode design --focus "issue # or area to improve" |
| Create a new factory mode | factory ceo /path/to/factory --mode create --focus "mode description" |
| Update an existing mode | factory ceo /path/to/factory --mode create --focus "improve: add plateau detection" |
re:factory doesn't just improve your project — it improves itself. Every keep/revert decision becomes training data for the next cycle.
This is powered by ACE (Autonomous Context Engineering) — inspired by Anthropic's work on context engineering — a Reflect → Curate → Inject loop that evolves agent playbooks from real experiment outcomes.
Each agent accumulates behavioral rules — DOs and DON'Ts — with evidence counters. Rules that correlate with kept experiments get reinforced. Rules that correlate with reverts get pruned.
See ACE Playbook Evolution for the playbook mechanics.
re:factory is a three-layer system:
Layer 1 — Python CLI (factory/): Pure tools that don't make decisions. Eval runner, strategy engine, experiment store, discovery, event logging. Entry point: uv run factory --help.
Layer 2 — CEO Agent (factory/agents/prompts/ceo.md): The orchestrator. Detects project state, spawns specialist agents, and makes the keep/revert decision for each experiment. Mode-specific playbooks are auto-generated from workflow graph definitions.
Layer 3 — Specialist Agents (factory/agents/): Eight independent Claude Code subprocesses — Researcher, Strategist, Builder, Reviewer, Evaluator, Archivist, Refiner, and Failure Analyst. Each has a focused prompt, receives context from the CEO, and returns structured output. Agent prompts support per-project overrides via .factory/agents/<role>.md.
Data flows down: the CEO calls the CLI for eval, store, and guard operations. Agents call nothing — they produce text that the CEO interprets.
Every change is measured by a composite score across three tiers:
| Tier | What it measures | Examples |
|---|---|---|
| Hygiene (6 dimensions) | Code quality basics | Tests, lint, type checking, coverage, guards, config |
| Growth (5 dimensions) | Capability evolution | API surface area, experiment diversity, observability, research effectiveness |
| Project (user-defined) | Domain-specific metrics | Benchmark accuracy, latency, win rate |
On first run, uv run factory discover auto-detects your project's language and framework to generate the eval profile. The weighted composite of all dimensions determines whether each experiment is kept or reverted. See Eval System for scoring details, weights, and guards.
re:factory has shipped something every day for the last 30 days — products, research experiments, production features, papers. Here are a few examples:
| Project | What it does |
|---|---|
| SWE-bench solver | Autonomous agent that resolves GitHub issues from the SWE-bench dataset, iteratively improved via failure analysis |
| HMMT math solver | Multi-agent team (Explorer, Theorist, Computationalist, Critic, Synthesizer) that solved HMMT Feb 2025 Combinatorics Problem 7 |
| Text/Sketch → CAD | Converts natural language and hand-drawn sketches into executable CadQuery code for 3D model generation |
| HLS design space explorer | Per-function AI agents explore HLS pragma/code variants in parallel, an ILP solver finds the optimal combination, then global expert agents apply cross-function optimizations — achieving up to 92% execution time reduction on cryptographic benchmarks |
| Pluck | iOS app that extracts structured data from screenshots, links, and shared content using on-device AI |
| Group chat digest | Turns iMessage group chats into weekly family newsletters with AI-curated highlights and photo selection |
| Production enterprise features | Complete UI components and backend features shipped into a large-scale production codebase |
| re:factory itself | re:factory runs on itself — its own agent playbooks are evolved from its own experiment outcomes |
Built something with re:factory? Open a PR to add it here.
Create mode lets you build new factory modes — new workflows, new pipelines, new factories. Pass a description via --focus to tell the CEO what mode to create. It's fully interactive — the CEO researches existing patterns, synthesizes a workflow spec, gets your approval, then implements everything: workflow definition, SKILL.md, CLI wiring, and tests.
factory ceo /path/to/factory --mode create --focus "a mode that validates PRs with multi-stage checks"To update an existing mode, prefix --focus with the mode name and a colon. The name before the colon is matched against registered workflows — if it matches, the CEO enters update mode instead of creating a new one:
factory ceo /path/to/factory --mode create --focus "improve: add plateau detection after 3 consecutive reverts"
factory ceo /path/to/factory --mode create --focus "build: add a code review gate after the builder"Without a colon, --focus always creates a new mode.
The pipeline: 3 parallel researchers (existing patterns, intent analysis, best practices) → Strategist synthesizes a workflow spec → you approve (like design mode) → Builder implements → QA verifies end-to-end → PR.
Point it at the factory repo itself to extend re:factory with custom pipelines.
# Design — brainstorm and build
factory ceo "idea" --mode design # Design from a raw idea
factory ceo ~/ideas/spec.md --mode design # Design from a spec file
factory ceo <path> --mode design # Design improvements for existing project
factory ceo <path> --mode design --focus "topic" # Seed with a specific topic
# Create — extend the factory
factory ceo <path> --mode create --focus "description" # Create a new factory mode
factory ceo <path> --mode create --focus "mode: change" # Update an existing modeSee factory --help for the complete list.
re:factory supports multiple CLI backends. Default is Claude Code — switch with --runner or FACTORY_RUNNER:
# Direct
CODEX_API_KEY="..." factory ceo /path --runner codex
BOBSHELL_API_KEY="..." factory ceo /path --runner bob
# Via config.toml profile (persistent)
factory ceo /path --profile codexConfigure profiles in ~/.factory/config.toml:
[credentials.codex]
FACTORY_RUNNER = "codex"
CODEX_API_KEY = "..."
[credentials.bob]
FACTORY_RUNNER = "bob"
BOBSHELL_API_KEY = "..."Run factory config show to see resolved config, or factory config edit to open the file. See Setup Guide for full details.
LangFuse provides LLM observability and tracing — track agent invocations, token usage, and execution flow across all factory runs.
# Start LangFuse services
scripts/langfuse-setup start
# Set the env vars the factory needs
export LANGFUSE_HOST=http://localhost:3000
export LANGFUSE_BASE_URL=http://localhost:3000
export LANGFUSE_PUBLIC_KEY=pk-lf-dev-local-key
export LANGFUSE_SECRET_KEY=sk-lf-dev-local-key
export TELEMETRY_PLATFORM=langfuseThe dev credentials above match the docker-compose setup. Add them to your ~/.bashrc or ~/.zshrc to persist across sessions.
- Start LangFuse:
scripts/langfuse-setup start - Run the factory:
factory ceo /path/to/project - Open
http://localhost:3000in your browser - Login:
dev@localhost.local/devpassword123
scripts/langfuse-setup start # Start LangFuse services
scripts/langfuse-setup stop # Stop services
scripts/langfuse-setup status # Show status and credentials- Docker or Podman — any of
docker compose,docker-compose, orpodman-composeworks
To disable tracing without stopping LangFuse:
export LANGFUSE_TRACING_ENABLED=falseFor LLM connection setup, trace structure details, and troubleshooting, see infra/langfuse/README.md.
re:factory is also distributed as a fully-bundled Claude Code plugin — agents, skills, and slash commands packaged together. A GitHub Actions workflow rebuilds the plugins branch of this repo on every push to main, so it always tracks the latest generated artifacts.
From inside Claude Code:
/plugin marketplace add akashgit/remote-factory#plugins
/plugin install factory@remote-factory
/reload-plugins
Once installed, the plugin exposes:
- The
/factory:implementslash command (entry point for the multi-agent pipeline). - Namespaced subagents — invoke with
factory:ceo,factory:researcher,factory:builder, etc. - The bundled skills under
.agents/skills/(e.g.pipeline-subagents,implement).
The plugin still shells out to the factory CLI for the heavy lifting, so you'll need the factory package installed globally as described in Quick Start.
To update later: /plugin marketplace update remote-factory. To remove: /plugin uninstall factory@remote-factory.
If you'd rather skip the marketplace and just register the specialist agents as standalone Claude Code (or Codex) subagents, use the built-in installer:
factory install # Install all 9 agents to ~/.claude/agents/
factory install --runner codex # Or install Codex TOML agents to ~/.codex/agents/
claude --agent factory-ceo "improve this project"
claude --agent factory-researcher "study the auth system"This path only ships the agent prompts (no skills, no slash commands) and is independent of the plugin marketplace install above.
Workflow graphs (Pydantic definitions) are converted to SKILL.md prose files that the CEO follows at runtime. This conversion goes through a verified pipeline to prevent information loss:
Workflow (Pydantic) → templatize → review agent → guard → split
│ │ │ │
{{slot::default}} opus structural SKILL.md +
+ annotations refines diff check annotations.yaml
The pipeline produces two artifacts per workflow:
- SKILL.md — clean prose the CEO reads at runtime
- SKILL.annotations.yaml — structured metadata per node for programmatic verification
Regenerate all skills after changing workflow definitions:
factory workflow export-skillsA regression test (test_annotations_match_source) runs in CI to catch drift between workflow definitions and exported skills.
| Doc | What's in it |
|---|---|
| Setup Guide | Installation, authentication, environment variables |
| Getting Started | Lifecycle walkthrough, research mode details, factory.md config |
| Architecture | Three-layer system, agent roles, state machine, data flow |
| Eval System | Hygiene/growth/project tiers, scoring, guards, precheck |
| Configuration | factory.md reference — all sections and options |
| ACE Self-Improvement | How re:factory evolves its own agent playbooks |
| Contributing | Dev setup, code style, testing, PR workflow |
| Contributing Benchmarks | How to add new benchmarks: workflow structure, Harbor setup, CI integration |
uv sync --all-groups # Install all deps including dev
uv run pytest -v # Full test suite
uv run ruff check . # Lint
uv run mypy factory/ # Type checkMIT — Akash Srivastava