AIFactory

Spec-Driven Development for AI agents — plan, code, ship.

Docs · Demo · Architecture · Roadmap · Contributing

📖 New here? Start at the docs → aifactory.freundcloud.com — guided demo, screenshots, architecture, and the full getting-started guide.

What it is

AIFactory turns GitHub issues into shipping code via a coordinated planner / coder / QA agent pipeline. You bring an issue (or a one-line task description) — AIFactory writes a spec, plans the work, codes it in an isolated git worktree, validates against the spec’s acceptance criteria, and hands you back a merge-ready branch.

You watch the whole thing happen live in the Agent Console — read-only by default, one-click Attach when you want to drive — or open the task in Mission Control, a full-page three-pane workspace (plan · live activity + console · preview / files / review). See docs/docs/concepts/mission-control-workspace.md.

🚀 What’s new (May 2026) — three more epics closed on top of the May MCP shipset:

Delegation (#92) — hand the coder phase off to GitHub Copilot Coding Agent or GitLab Duo Workflow while AIFactory keeps the planning + governance. Hybrid only: planner runs on Claude, the structured plan lands as a comment on the issue, then the provider’s agent codes. See docs/docs/concepts/delegation.md.

Portal-managed Git clones (#82) — point the portal at a Git URL, it clones into a workspace root (laptop default ~/.aifactory/workspaces/, Helm-templated PVC on K8s). Stored Personal Access Tokens encrypted at rest. Required for SaaS / Kubernetes deployments. See docs/docs/concepts/portal-clones.md.

Scoped MCP API keys (#154) — replace the host-wide admin token at ~/.aifactory/.token with per-developer scope-gated acw_ keys. Mint via Settings → API Keys, drop in $AIFACTORY_MCP_KEY, done. Legacy admin token still works as a wildcard fallback. See docs/docs/concepts/mcp-stdio-keys.md.

Earlier May 2026 shipset (still current): 27 MCP tools across stdio + remote HTTP+SSE transports, the /handover skill for Claude Code, default MCP servers that auto-enable per project, and Remote Control wiring for claude.ai/code on any device.

See guides/HANDOVER_WORKFLOW.md for the developer flow, guides/CLAUDE_CODE_MCP_TOOLS.md for the stdio tool catalog, and guides/REMOTE_MCP_SERVER.md for the HTTP+SSE server (Cursor / Continue.dev / non-Claude clients).

Enterprise v1.1 (May 28, 2026 — Epic #35)

AIFactory ships 7 major enterprise features — multi-tenant isolation, observability, audit hardening, and IdP integration for regulated deployments. All features are opt-in via Helm values; default deployments remain unchanged.

Capability	Issue	Concept doc
SAML 2.0 + SCIM 2.0 — Legacy IdP federation (ADFS-era banks, Azure AD provisioning)	#41	saml-scim
Tenant Isolation Mode — Per-tenant K8s namespace + NetPol + S3 + Vault + leader election	#36	tenant-isolation
LiteLLM Gateway — Per-org budget + rate-limit + allowlist + PII-redacted audit log	#38	litellm-gateway
Bedrock + Vertex Routing — Cloud-provider LLMs (AWS, Google) via LiteLLM	#39	cloud-llm-routing
Signed Audit-Chain Anchor — Daily HMAC-anchored chain for ISO 27001 A.12 compliance	#43	audit-anchor
OpenTelemetry Distributed Tracing — W3C `traceparent` across web + agent + subprocess	#42	observability-tracing
gVisor Sandbox — Agent pods opt-in to gVisor RuntimeClass for kernel-level isolation	#37	—

Multi-replica support: S3 workspace storage + Redis pub/sub (#40) enable horizontally scaled deployments.

What’s next: v1.2 roadmap includes Claude-on-LiteLLM enforcement wrapper, per-tenant audit anchors, and SAML Single Logout — tracked in Epic #204.

Why it’s different

Spec-first, not vibe-first. Every agent run starts from a written, reviewable spec with acceptance criteria. Plans are editable before code is written.
Multi-provider by design. Pick a model per phase. Plan with Claude Opus, code with a cheap local Ollama qwen3, validate with Sonnet. Anthropic / OpenAI / Ollama / Gemini / Codex / any OpenAI-compatible endpoint.
MCP control plane. 27 tools across two transports let any MCP-aware editor inspect and direct AIFactory. The /handover skill turns “this is bigger than I thought” into an autonomous overnight run with one keystroke. Scope-gated per-developer keys in v1.1 mean shared hosts and SaaS deployments don’t hand out admin power.
Provider-agent delegation. On GitHub repos, AIFactory can hand the coder phase off to Copilot Coding Agent; on GitLab, to Duo Workflow. AIFactory still authors the spec + plan; the provider’s agent does the typing. Cuts Claude spend ~10× for delegated tasks.
Portal-managed clones. Point AIFactory at a Git URL and it clones into a workspace PVC (on K8s) or a configurable workspace root (on laptops). Stored PATs are encrypted at rest. Required for SaaS / Kubernetes installs.
Infra-aware out of the box. A catalog of default MCP servers (Kubernetes, AWS, Azure, GitHub) auto-enables per project when markers + credentials line up. Read-only by default, audit-logged, CVE-aware version pins.
One screen to drive a task. Mission Control puts the plan, the agent’s live activity + embedded terminal, and the output (running preview, diff, or merge controls) side by side — no tab-switching while a build runs.
Isolated by default. Each task runs in its own git worktree. Nothing touches your working tree until you merge.
Auditable. Hash-chained audit log, on-disk specs+plans+QA reports, full SOC2 evidence catalog in the enterprise build.

Quickstart (60 seconds)

git clone https://github.com/olafkfreund/AIFactory
cd AIFactory
npm run install:all
claude setup-token   # paste into apps/backend/.env as CLAUDE_CODE_OAUTH_TOKEN

Start the two servers (in separate terminals):

cd apps/web-server  && python -m server.main         # :3101
cd apps/frontend-web && npm run dev                  # :3100

Open http://localhost:3100 and create your first project.

Full installation guide: Getting Started →

See it work

![Terminal walkthrough — clone the demo repo, file a GitHub issue, type /handover in Claude Code, watch AIFactory's planner / coder / QA pipeline produce a merge-ready branch](/AIFactory/static/img/handover-workflow.gif)

A 45-second terminal walkthrough of the /handover workflow: clone the demo repo, file a GitHub issue, type /handover in Claude Code, AIFactory’s planner → coder → QA pipeline lands at a merge-ready branch. Every artifact shown was produced by a real agent run — the recording compresses the timeline.

The repo also ships a scripted end-to-end demo that exercises the whole pipeline against a public sample repo:

./scripts/demo.sh

It seeds 3 GitHub issues, registers the demo repo with your portal, imports the issues as backlog tasks, prompts you to drive Claude Code from the terminal, then kicks off an autonomous build — all in about 90 seconds. Pass --yolo to skip the Enter-prompts between steps.

Walkthrough with screenshots + browser-side video: Demo →

Screenshots

MCP servers view

Screenshots are auto-captured by scripts/capture-screenshots.ts from the live portal — refresh them with npm -w apps/frontend-web run capture-screenshots. A fuller, captioned set lives in the Screenshot gallery.

Documentation

The full documentation lives at https://aifactory.freundcloud.com/:

Getting Started — install + first task
Demo — guided end-to-end walkthrough
Concepts — spec-driven development, multi-provider routing, the rmux Live Console
Architecture — agents, data flow, security model, Mermaid diagrams
Wiki — FAQ, troubleshooting, glossary
Compliance — SOC 2 evidence, GDPR, encryption-at-rest

Legacy guides (pre-2026-05-26 rewrite) are archived under docs-archive/2026-05-26/ and remain searchable in git history.

Stack

Frontend — React 19 + Vite + xterm.js + Tailwind v4
Web Server — FastAPI + WebSocket, Postgres + Alembic migrations
Agent Runtime — Python 3.12, Claude Agent SDK, provider abstraction over Anthropic / OpenAI / Ollama / Gemini / Codex
Deploy — Helm chart (charts/aifactory/), distroless cosign-signed images, OIDC SSO, KMS-backed encryption at rest

Contributing

Branching: dev is the working branch. Branch from origin/dev, sign your commits (git commit -s), open PRs against dev. main is a release branch and only receives promotion merges.

git fetch origin
git checkout -b feat/my-feature origin/dev
git push -u origin feat/my-feature
gh pr create --base dev

CI runs ruff + pytest + frontend typecheck + Postgres acceptance + multiple compliance gates on every PR. Full guide: Contributing →

License

Dual-licensed under MIT or GPL-3.0 at your option — see LICENSE, LICENSE-MIT, and LICENSE-GPL.

Acknowledgements

Built with the Claude Agent SDK, FastAPI, Docusaurus, and rmux (terminal multiplexer fork in Rust, used for the Live Console).

This site is open source. Improve this page.