Skip to content

setup.md

Latest commit

 

History

History
163 lines (115 loc) · 6.11 KB

setup.md

File metadata and controls

163 lines (115 loc) · 6.11 KB
Raw

Setup Guide

Prerequisites

Tool Version Install
Python 3.11+ System or pyenv
Claude Code Latest npm install -g @anthropic-ai/claude-code
Node.js 18+ Required for Claude Code and MCP servers
uv Latest curl -LsSf https://astral.sh/uv/install.sh | sh (auto-installed by Option A)
tmux Any brew install tmux (optional, for long-running sessions)

Claude Code must be installed and authenticated. re:factory spawns claude as subprocesses — it does not call the Claude API directly. However you've authenticated Claude Code (API key, Vertex AI, etc.) is how re:factory will access Claude.

Installation

Install re:factory globally so the factory command is available everywhere on your machine. This is important because factory creates worktrees that are not guaranteed to inherit the local environment, but we need factory agents to be able to correctly call factory commands via CLI regardless of the location of the git worktree.

Option A: One-liner (recommended; installs uv if necessary)

curl -sSf https://raw.githubusercontent.com/akashgit/remote-factory/main/install.sh | bash

Option B: uv

uv tool install git+https://github.com/akashgit/remote-factory.git

Option C: From source (for development)

re:factory evolves fast — installing from source lets you git pull to stay current.

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

Verify

factory --help

CEO Agent Registration

Register re:factory CEO as a Claude Code agent so you can launch it from anywhere:

factory install

This writes ~/.claude/agents/factory-ceo.md. Now you can:

# From any terminal
factory ceo ~/my-project

# From within any Claude Code session
claude --agent factory-ceo

Re-run factory install after updating re:factory to pick up prompt changes.

MCP Servers

re:factory uses MCP for extended capabilities. Configuration lives in .mcp.json at the project root:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Playwright MCP enables browser automation for UI testing. Claude Code auto-discovers .mcp.json — no manual setup needed.

To add MCP servers to a target project, create a .mcp.json in its root. The Builder agent will use available MCP tools when working on that project.

What You Don't Need

  • No Obsidian. re:factory stores all state locally in .factory/ inside each project and ~/.factory/ globally. Earlier versions used an Obsidian vault — that dependency has been removed entirely.
  • No external database. Everything is flat files: TSV for experiment history, JSON for config and reports, markdown for strategy and archive notes.
  • No API keys for re:factory itself. re:factory spawns Claude Code subprocesses — however you've authenticated Claude Code is how re:factory accesses Claude. No separate Anthropic API key is needed.

Environment Variables

re:factory reads these environment variables. None are required for basic usage — the defaults work out of the box.

Tip: All FACTORY_* variables below can also be set in ~/.factory/config.toml, which supports credential profiles and secret masking. See the Configuration Reference for details. Env vars always take precedence over config.toml values.

Claude Code Authentication

re:factory inherits Claude Code's authentication. Configure whichever method you use:

Variable Purpose
ANTHROPIC_API_KEY Direct API authentication
CLAUDE_CODE_USE_VERTEX Set to 1 for Google Cloud Vertex AI
ANTHROPIC_VERTEX_PROJECT_ID Vertex AI project ID
CLOUD_ML_REGION Vertex AI region (e.g., us-east5)
CLAUDE_CODE_USE_BEDROCK Set to 1 for AWS Bedrock

When one of the variables above is set, re:factory's Claude Code subprocesses launch with --bare for faster startup (skips hooks, LSP, and plugin loading). --bare never reads the OAuth keychain, so it's skipped automatically for subscription (Pro/Max) logins — those keep working exactly as claude does on its own, just without the startup optimization.

re:factory Configuration

Variable Purpose Default
FACTORY_PROJECTS_DIR Parent directory for projects created from prompts ~/factory-projects
FACTORY_MODEL Model override for agent subprocesses (Claude Code default)
FACTORY_PLAYBOOKS_DIR Directory for ACE-evolved agent playbooks ~/.factory/playbooks
FACTORY_REGISTRY_DIR Override global registry location ~/.factory
FACTORY_VAULT_PATH Legacy: path to Obsidian vault (optional, for Archivist) (unset — not needed)
FACTORY_RUNNER CLI backend claude
FACTORY_RUNNER_QUIET Suppress runner output (1 to enable) (unset)

Notifications (optional)

Variable Purpose
TELEGRAM_BOT_TOKEN Telegram bot token for push notifications
TELEGRAM_CHAT_ID Telegram chat ID for notifications

CEO Behavior (advanced)

Variable Purpose Default
FACTORY_CEO_RESPAWN_DISABLED Disable automatic CEO respawn on crash (1) (unset)
FACTORY_CEO_MAX_RESPAWNS Maximum respawn attempts per cycle 3

Full Setup From Scratch

# 1. Install tooling
npm install -g @anthropic-ai/claude-code     # Claude Code

# 2. Authenticate Claude Code (if not already done)
claude  # follow the prompts

# 3. Install re:factory globally
uv tool install git+https://github.com/akashgit/remote-factory.git

# 4. Register CEO agent
factory install

# 5. (Optional) Set up config file with credential profiles
factory config edit                          # Creates ~/.factory/config.toml

# 6. Verify
factory --help
factory detect /path/to/any/project