Foundry
TypeScript tools and libraries for working on codebases locally. Some of them
bring coding agents into the work; all of them run on your machine, keep their
state on disk, and send nothing anywhere unless you tell them to.
Foundry is a Bun and Turborepo workspace. Marbles and Spyglass are configured as
standalone npm packages; the shared libraries they bundle remain private.
Tools
| Package | What it does | Read more |
|---|
| Marbles | Turns recurring automations into inspectable TypeScript. Modules in .foundry/marbles/ define steps, workflows, agents, schedules, and monitors. Run them once or keep Marbles running in a terminal. | README · Docs |
| Spyglass | Draws a workspace of TypeScript packages as a map you explore in the browser. Packages are islands placed by dependency, files are their settlements. | README · Docs |
Apps release independently. Marbles is packaged as @foundry.sh/marbles and
starts at 0.0.1 (alpha), with breaking changes allowed throughout 0.0.x
until the 0.1.0 API milestone. Shared libraries have one synchronized internal
version and remain private, without their own release PRs or GitHub Releases.
Spyglass release automation is deferred until its rename. GitHub Releases are prepared separately
from manually dispatched npm publication. The first npm release has not shipped
yet; until then, run the tools from this repository.
Libraries
Private workspace packages. Marbles bundles the ones it uses.
| Package | What it does |
|---|
| agents | The agent runtime: a tool-calling loop over an AI SDK model, a persisted conversation, MCP servers, skills, and an authorization gate on every tool call. |
| workflows | A durable workflow runtime. Steps compose into trees, run under a queue, survive a restart, and can suspend waiting on a human. |
| tasks | The backlog: what there is to do, what is ready, what is done. Tasks with dependencies and parents, derived availability, and one atomic batch command. Execution stays in workflows. In memory by default; a TaskStore persists it. |
| models | One registry over hosted gateways, on-device weights, and the coding-agent CLI harnesses, plus the catalog of what each model costs and can do. |
| workspaces | Durable registration of a source directory: identity, inclusion, and the last reconciled inventory of its files. |
| artifacts | Versioned content with stable identity, blob storage, and delivery to the filesystem. |
| sandbox | One Sandbox interface over a microVM container or an in-memory filesystem, with one set of agent tools bound to either. |
| core | Dependency-free storage and pagination contracts shared by the packages above. |
|
tooling/ holds the release scripts and the shared TypeScript configuration.
Documentation
The site at francois-esquire.github.io/foundry
has a section per tool: Marbles
and Spyglass.
The pages live in this repository under docs/: docs/marbles
and docs/spyglass, built with Blume. Run the site locally with:
bun install --frozen-lockfile
bun run docs:dev
Each package README covers its own API and development commands.
Website
apps/foundry.sh is the static Astro marketing site for
foundry.sh. It introduces the broader creation-tooling vision and links to the
documentation. Run it with bun run dev --filter=@foundry/website.
Contributing
Development uses Bun and Turborepo. See CONTRIBUTING.md for
setup, checks, documentation development, and publishing.
License
MIT
