Foundry

Spec-driven development with AI. Write the spec, let AI build it.

Features • How It Works • Getting Started • Development • Building • Architecture • Contributing • License

---

Warning

This project is a playground for the author to test out building ideas for open-source project using agentic development. It is not intended to be fully secure and operational. Feel free to fork if you want to make the idea viable.

---

Foundry is an Electron-based IDE where you collaborate with an LLM to write markdown specification files that define a software project. Each commit of your spec triggers an AI coding agent to produce a complete, working implementation as a standalone artifact.

You iterate on the spec, inspect the generated code, run tests, and get feedback from expert review agents — all within the same app. No API keys required — Foundry uses locally installed Claude Code or Codex CLI tools.

Features

Design Tab

Write and refine your project spec using a Notion-like WYSIWYG editor (BlockNote). A chat panel lets you discuss changes with an AI assistant that can directly edit your spec files. Highlight text to add inline comments that get batched and sent to the assistant.

Inspect Tab

Browse the generated implementation code with a full Monaco editor — file tree, tabs, minimap, and syntax highlighting for every language. Watch builds in real-time with streaming agent output.

Test Tab

Run tests against the implementation, view results with a visual pass/fail summary, and launch the built artifact to preview it. Test output renders with ANSI color codes.

Review Tab

Get feedback from configurable expert agents — QA Analyst, Security Analyst, UX/UI Designer, Performance Engineer, or your own custom roles. Each expert reviews the full spec + implementation and provides actionable feedback with streaming responses.

Settings

Configure providers (Claude Code / Codex), models, build commands, test commands, and screenshot capture. Per-expert provider/model overrides supported. Settings work as global defaults and per-project overrides.

How It Works

Write Spec (.md files)  →  Commit  →  AI Agent Implements  →  Inspect / Test / Review
       ↑                                                              ↓
       └──────────── Iterate based on feedback ───────────────────────┘

1. Design your project spec as a collection of markdown files (overview, architecture, features, tests)
2. Commit your spec — this triggers the AI agent (Claude Code or Codex) to implement the entire project from scratch in a git worktree
3. Inspect the generated code in a full-featured code editor
4. Test the implementation by running your test suite and launching the built artifact
5. Review the code with expert agents who provide detailed feedback
6. Iterate — refine your spec based on feedback and commit again

Each commit produces a standalone artifact. The spec is the source of truth.

Prerequisites

• Node.js >= 18
• Bun >= 1.0 — Install Bun
• Git — for version control of spec and implementation repos
• At least one AI coding agent installed and authenticated:
  • Claude Code — npm install -g @anthropic-ai/claude-code
  • Codex — follow OpenAI's install instructions

Getting Started

# Clone the repository
git clone https://github.com/user/foundry.git
cd foundry

# Install dependencies
bun install

# Start in development mode
bun run dev

This builds all packages, starts the Vite dev server, and launches the Electron app.

Development

Project Structure

foundry/
  apps/
    desktop/          # Electron shell (main process, preload)
    server/           # Node.js backend (event sourcing, git, providers, WS)
    web/              # React frontend (Vite, shadcn/ui, Tailwind, Monaco, BlockNote)
  packages/
    contracts/        # Shared TypeScript types (WS protocol, IDs)
    shared/           # Shared utilities (logging, port finder)

Tech Stack

Layer	Technology
Desktop	Electron
Frontend	React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui
Spec Editor	BlockNote (Notion-like WYSIWYG)
Code Editor	Monaco Editor
State	Jotai (frontend), Event Sourcing + CQRS (server)
Backend	Node.js, WebSocket (JSON-RPC), SQLite
Agent Harness	Claude Code CLI, Codex CLI (spawned as subprocesses)
Build	Turborepo, Bun

Scripts

Command	Description
bun run dev	Start dev mode (Vite + Electron)
bun run build	Build all packages
bun run typecheck	Type-check all packages
bun run package	Build and package as standalone macOS app
bun run clean	Clean all build artifacts

Key Design Decisions

• No API keys required — All LLM interaction goes through locally installed CLI tools (Claude Code, Codex). The user authenticates once with the CLI, and Foundry uses it.
• Event sourcing — All state changes (project creation, spec edits, artifact builds, reviews) are stored as immutable events in SQLite. The read model is rebuilt from events on startup.
• Separate repos — The spec (markdown files) and implementation (generated code) live in separate git repos. Each artifact gets its own git worktree.
• Single-shot artifacts — Each spec commit produces a fresh, complete implementation. Simpler than incremental diffing; the spec is always the source of truth.
• Provider adapters — Claude Code and Codex are abstracted behind a common interface. Prompts are piped via stdin to avoid argument length limits.

Building

Development Build

bun run dev

Package for macOS

bun run package

This produces signed .dmg files for both ARM64 (Apple Silicon) and x64 (Intel) in the release/ directory.

Code Signing & Notarization

To distribute the app, create a .env.local file with your Apple credentials:

CSC_NAME="Developer ID Application: Your Name (TEAMID)"
APPLE_ID="your@email.com"
APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
APPLE_TEAM_ID="XXXXXXXXXX"

Without these, the app is built unsigned (users right-click > Open to bypass Gatekeeper).

See Apple's developer documentation for details on obtaining certificates.

Architecture

┌─────────────────────────────────────────────────────┐
│                 ELECTRON MAIN PROCESS                │
│  BrowserWindow, server spawn, shell PATH resolution │
└──────────┬──────────────────────┬────────────────────┘
           │ fork()               │ preload bridge
           v                      v
┌──────────────────┐   JSON-RPC  ┌─────────────────────┐
│  SERVER (Node.js) │◄──── WS ──►│   REACT FRONTEND     │
│                   │            │                       │
│  Event Store      │            │  Design  │ Inspect    │
│  (SQLite)         │            │  Test    │ Review     │
│                   │            │  Settings             │
│  Provider Service │            └─────────────────────┘
│  (Claude / Codex) │
│                   │──► SPEC REPO (user's .md files)
│  Git Layer        │──► IMPL REPO (agent-generated code)
│  Screenshot Svc   │──► Puppeteer (configurable)
└──────────────────┘

Data Flow

1. Frontend sends commands via WebSocket JSON-RPC
2. Server validates commands through the Decider (CQRS pattern)
3. Events are appended to the SQLite Event Store
4. The Projector folds events into the in-memory read model
5. Changes are broadcast to all connected clients via WebSocket push
6. Side effects (agent runs, screenshots, tests) are triggered by event listeners

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Tips

• The frontend hot-reloads via Vite HMR
• After running bun run package, run bun install to restore native modules for dev
• SQLite database is stored at ~/.foundry/foundry.db
• Project data (spec repos, impl worktrees) lives at ~/.foundry/projects/

License

MIT

---

Built with Claude & Electron