factory-agent 0.1.0

Factory — AI engineer that picks up tickets and ships code

Factory

Your AI engineer. Assign a ticket, get a PR.

---

Factory is an autonomous coding agent that takes a Linear ticket and delivers a pull request — code, tests, review, security scan, and all. Five specialized AI agents collaborate in a pipeline that learns from every run.

pip install factory-agent
factory init          # 60-second setup wizard
factory run GHO-42    # ticket in, PR out

That's it. Go review your PR.

---

How it works

When you run factory run, five agents execute a structured pipeline:

                         ┌─────────────────────┐
                         │      factory run     │
                         └──────────┬──────────┘
                                    │
                         ┌──────────▼──────────┐
                         │    Atlas (opus)      │
                         │    Orchestrator      │
                         │    Plans the work,   │
                         │    never writes code │
                         └──────────┬──────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              │                     │                      │
   ┌──────────▼──────────┐  ┌──────▼───────┐  ┌──────────▼──────────┐
   │   Scout (sonnet)    │  │              │  │   Cipher (haiku)    │
   │   Read-only recon   │  │   Builder    │  │   Security scan     │
   │   Finds files,      │  │   (opus)     │  │   OWASP top 10,     │
   │   maps patterns,    │  │              │  │   injection,        │
   │   gathers context   │  │   Writes     │  │   secrets, auth     │
   └──────────┬──────────┘  │   code &     │  └──────────┬──────────┘
              │              │   tests      │              │
              └──────────►  │              │  ◄────────────┘
                            └──────┬───────┘
                                   │
                          ┌────────▼────────┐
                          │  Lens (haiku)   │
                          │  Quality gate   │
                          │                 │
                          │  APPROVE ──────────► commit & open PR
                          │                 │       │
                          │  REJECT ───┐    │       ▼
                          └────────────┘    │   Linear comment
                                │           │   with result
                                ▼           │
                          Back to Builder   │
                          (max 2 retries)   │
                                            │

Every agent has a single responsibility and constrained permissions. Scout and Lens are read-only — they can't modify your code. Builder writes but doesn't orchestrate. Atlas orchestrates but doesn't write. This separation prevents the failure modes of single-agent systems.

Quickstart

1. Install

pip install factory-agent

2. Configure

factory init

Interactive wizard that:

• Validates your Anthropic API key
• Authenticates your GitHub PAT against the API
• Verifies your Linear API key
• Auto-detects your repo from git remote

Config is saved to .factory/config.yaml (auto-gitignored).

3. Run

# Process a single ticket
factory run https://linear.app/your-team/issue/TEAM-123

# Or just use the identifier
factory run TEAM-123

4. Watch (continuous mode)

# Poll Linear every 5 minutes, auto-process new tickets
factory watch

# Custom interval
factory watch --interval 120

CLI Reference

factory init                    Interactive setup wizard
factory run <ticket>            Process a single Linear ticket
factory watch [--interval N]    Continuously poll and process tickets
factory status                  Show recent runs
factory status --costs          Show cost breakdown
factory status --patterns       Show learned patterns

Memory: The agent that learns

Factory doesn't start from scratch every time. A persistent memory layer tracks what works and what doesn't across runs:

Store	What it captures
Patterns	Weighted approaches — successful strategies get boosted, failures get suppressed. Injected into future prompts automatically.
Observations	Facts about your codebase gathered during runs — file structure, conventions, test patterns.
Runs	Full execution history with timing, token usage, and outcomes.
Transitions	Agent-to-agent handoff trace for debugging pipeline behavior.

Run 1 might take 8 minutes. By run 10, the agent knows your codebase conventions, your test patterns, and which approaches work — and it's faster.

# See what the agent has learned
factory status --patterns

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Linear API  │────▶│   Factory    │────▶│   GitHub     │
│  (tickets)   │     │   Pipeline   │     │   (PRs)      │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
                     ┌──────▼───────┐
                     │   Memory     │
                     │   (SQLite)   │
                     │              │
                     │  Patterns    │
                     │  Observations│
                     │  Run history │
                     └──────────────┘

Agent stack: Built on LangGraph with Claude (Opus, Sonnet, Haiku) via the Anthropic API. Each agent runs in a sandboxed environment with controlled tool access.

Cost model: Opus for planning and implementation (where quality matters), Haiku for review and security (where speed matters), Sonnet for analysis (balance of both). A typical ticket costs $2-8 depending on complexity.

Configuration

.factory/config.yaml:

anthropic_api_key: sk-ant-...
github_token: ghp_...
linear_api_key: lin_api_...

repo:
  owner: your-org
  name: your-repo

linear:
  team_id: your-team-uuid
  team_name: YourTeam

# Optional — all have sensible defaults
model: anthropic:claude-opus-4-6
max_tokens_per_run: 500000
max_daily_runs: 20
max_daily_cost: 50.0

Environment variables override config values: ANTHROPIC_API_KEY, GITHUB_TOKEN, LINEAR_API_KEY.

Cost controls

Factory enforces spending limits so you don't wake up to a surprise bill:

Control	Default	Description
max_daily_runs	20	Maximum pipeline runs per day
max_daily_cost	$50	Maximum estimated spend per day
max_tokens_per_run	500K	Token cap per individual run

Budget checks run before each pipeline execution. If a limit is hit, the run is blocked with a clear message.

# Monitor spending
factory status --costs

Self-hosting

Factory can also run as a LangGraph server for webhook-driven, always-on usage:

pip install "factory-agent[server]"
SANDBOX_TYPE=local langgraph dev

The [server] extra adds FastAPI, uvicorn, and cloud sandbox providers (Daytona, Modal, Runloop). This mode accepts inbound webhooks from Linear, Slack, and GitHub for fully automated ticket processing.

See INSTALLATION.md for Docker Compose and Fly.io deployment.

Development

git clone https://github.com/ajsai47/factory.git
cd factory
pip install -e ".[dev,server]"
pytest

License

Apache 2.0 — see LICENSE.

Built on Open SWE by LangChain, Inc. (MIT). See NOTICE for attribution.