Home

Foundry overview

Foundry is a native macOS Electron app that runs repeatable agent-plus-code pipelines against your git repos. You describe the work, pick (or design) a pipeline, and a deterministic TypeScript engine sequences bounded agent phases, code commands, and optional human interrupts. Every event lands in a per-project SQLite trace that the UI polls live.

This repository holds two related things. Foundry (apps/desktop/) is the active product. The original Python skill under .claude/skills/sssf/ is the idea source (phases, envelopes, gates, earned success, poll-don't-push). Foundry reimplements those ideas in TypeScript and does not import or run the skill.

Who uses it

• Operators who want plan → build → test → review to run the same way every time, while watching swim lanes fill.
• Tuners who edit the agent roster, swap models, add gates, and tighten write boundaries in the UI.
• Skeptics who open a finished run and ask what was verified: gate evidence, costs, prompts, and raw JSONL are one click deep.

Table of contents

Overview

• Architecture
• Getting started
• Glossary

Snapshot and history

• By the numbers
• Lore
• Fun facts

How to contribute

• How to contribute
  • Development workflow
  • Testing
  • Debugging
  • Patterns and conventions
  • Tooling

Apps

• Apps
  • Foundry desktop

Systems

• Systems
  • Engine
  • Droid harness
  • Trace
  • Store
  • IPC and preload
  • System services
  • Renderer

Features

• Features
  • Pipelines
  • Roster
  • Runs and traces
  • Envelopes and gates
  • Worktrees
  • Onboarding

Primitives

• Primitives
  • Phase
  • Envelope
  • Gate
  • Pipeline
  • Agent

Background and security

• Background
  • From SSSF to Foundry
  • Design invariants
• Security

Reference

• Reference
  • Configuration
  • Data models
  • Dependencies

Doctrines in one line each

1. Code owns the loop. The engine owns sequencing, retries, and acceptance. Agents work inside one phase and never decide whether they succeeded.
2. Typed seams. Context crosses phases only as validated envelopes (zod) plus handoff files. Parse failures re-prompt the same live session.
3. Poll, don't push. The main process writes SQLite (WAL); the renderer polls with a rowid cursor. Live view and history are the same query.