Yesod is a tool registry, task graph, agent mail system, cost-aware dispatcher, and coding factory for building software with AI agents. I tend to follow the Unix philosophy: have a large number of simple, reliable tools that can be stitched together to accomplish things. Over time, I created many of these custom tools, and it became easy to forget about them. So Yesod started as a simple Markdown file listing my custom tools, what they do, and how to use them.
Maintaining this Markdown file was cumbersome, so I built a custom CLI tool and skill. Calling yesod tools list would always show an up-to-date list of the available tools and a brief description of what each one did. Combined with good --help documentation, this allowed my agents to progressively discover the tools available to them. I think humans are great at knowing the big picture—for example, recognizing when all the tools are there to solve a particular problem. AI is great at taking a large collection of facts and creating a plan.
Occasionally, the agents would discover bugs in my tools. I wanted them to be able to do something with that knowledge. So I upgraded Yesod with the following syntax:
yesod tool {tool-name} bug-report "...A BUG REPORT..."This worked really well. So I expanded the types of input Yesod could gather to include feature requests and usage notes. With bug reports and feature requests streaming in, it naturally led to the following idea:
What if Yesod could implement the requested features and fix the reported bugs? That would be cool.
Thus began an adventure. Yesod is now:
- A system of record for the development of all of my CLI tools. This includes up-to-date usage guidelines, bug reports, and feature requests.
- A command-line tool that agents can use to discover the tools available to them.
- A repository of repeatable processes meant to be followed by agents. See “Yesod Processes” for details.
- A way for agents using one tool to file bug reports, usage notes, and feature requests against another tool.
- A monitoring system for how these tools get used.
- A dispatcher that routes bugs and feature requests to a software factory that can fix or implement them.
- A cost-aware dispatcher that can route agentic tasks to the cheapest model that can reliably do the job. Currently, the highest-tier models are GPT-5.6 Sol and Fable 5. For medium-tier “workhorse” models, Kimi K3 and GLM-5.3 are perfect. Models such as DeepSeek V4 Pro and MiniMax M3 work at the low end.
- A platform for understanding the tradeoffs between different up-front planning costs and the quality of execution.
- A messaging and mailing platform between agents.
- A coding factory.
Background
I have been working on a project for the past few months. I am calling it Yesod, which is the Hebrew word for “foundation.” I named it this because I want Yesod to be the foundation of my development and tools.
For reference, in one of my contract roles, I advise organizations on how to use AI cost-effectively. It’s easy to say, “Model X could do that at lower cost,” but changing established processes is hard. If you’re comfortable using Claude Code with Fable 5, you may end up using it for everything—especially when the person choosing the model is not directly responsible for the bill.
Part of developing Yesod was to separate the model you interact with from the model doing the work. When working with Yesod, you talk to a foundation model that creates tasks for the Yesod software factory.
Footnote on the Name
The name is pronounced “yeh-SODE” (/jeˈsod/), with the stress on the second syllable. There is a Haskell project also called Yesod. I really liked this project and used it in its heyday. It is still an active project, so there is a bit of a name collision. Technically, my project is called Yesod.work—“Yes-ode dot work.”
I believe that the problem domains are separate enough that the Yesod Web Framework is distinct from Yesod.work. The name is a tribute and is meant to be taken as such.
Where This Article Fits
Think of this as the front door to a series about Yesod. I’ll explain what motivated me to build it, establish the terminology, and end with a concrete example of working with the mayor—the agent that coordinates the software factory. Future articles will go deeper into the architecture, operations, economics, and other ways I use Yesod.
Upcoming in This Series
Here is the current working list. The titles and order may change as the factory does.
- Using LambdaVM for High-Performance Merge Gating in a Software Factory
- How to Effectively Use Beads + Dolt at Scale
- Give Your AI Access to Infrastructure—an Experiment with Proxmox
- Yesod Factory—A Software Factory Architecture
- When an AI System Reaches Critical Mass—the moment the factory encountered a bug, filed a report against itself, fixed it, and redeployed itself
- Agentic Roles in a Software Factory
- Decoupled Agents in a Software Factory
- Yesod Processes—Making Your AI Processes Repeatable
- Yesod Mail—Easy-to-Use Messaging Between Agents
- Yesod Toolbox—What Happens When Your Tools Know About Each Other?
- Yesod Distillations—Capturing Best Practices in a Changing System
- Making Your Factory Cost-Aware
- Yesod Ask
- Yesod Query
- Yesod Get
- Experiments with Semantic Preprocessing and Graph Databases
Key Data and Architecture
To make the rest concrete, here are the terms I use for Yesod’s main parts and the work that moves between them.
Tool — A project that I want Yesod to track. The purpose of Yesod is to manage my tools, my teams’ tools, and how they work together. For example, aysp, hnalg, media-tooling, and nbgen are all tools. Each has a GitHub repository.
Note — The durable anchor for a piece of work inside the factory. A Note records the intent and keeps its discussion, status, planning, and execution tied together. Notes are stored in a PostgreSQL database and scoped to a tool. A Note has a simple identifier of the form ys-{tla}-{4lid}, where tla is a three-character tool prefix and 4lid is a four-character identifier that uniquely identifies the Note. For example, an identifier like ys-yes-j42c would refer to a Note about Yesod.1
There are three types of notes: usage-note, bug-report, and feature-request. The key insights about notes are:
- Usage notes are how AI agents and I remember what we learn while working with a tool. Whenever one of us discovers a useful technique, constraint, or surprise in the course of getting something done, a usage note captures it for reuse. Yesod mines these notes for recurring insights and patterns, turning individual observations into a living memory for the factory.
- Feature requests capture a capability a tool does not yet have and explain why it would be valuable. An agent that encounters such a gap can file the request directly in Yesod instead of tracking down the tool’s GitHub repository. All of my AI agents can create feature requests, bug reports, and usage notes this way. They are meant for capture: if you have an idea, you might as well fire off a feature request. This doesn’t obligate you in any way.
- Bug reports work the same way. If an AI agent is using a tool and, in its best judgment, the tool is failing to do something it says it should do, the agent can file a bug report.
Beads — Beads are an excellent invention from Steve Yegge and are now maintained by the Gas Town community. Rahul Subramaniam wrote a great article about how task graphs keep agents from skipping steps.
The idea is that a Bead is a durable unit of work in a dependency graph. Beads give agents a shared task structure that survives individual sessions and makes ready and blocked work queryable. In Yesod, a feature-request or bug-report Note links to a root Bead. Its child Beads hold the checklist, sequencing, and progress for that feature.
Runner — A simple worker daemon that executes dispatched work. My Linux runners live on their own VMs on a Proxmox host, but a runner could also easily be an EC2 instance or other cloud infrastructure. My current fleet includes one macOS runner (an M1 MacBook with a broken screen) and three Linux runners.
Grounding — Turning a Note into a detailed, executable plan by inspecting the project, linking a root Bead, adding instruction and checklist Beads, and recording the necessary dependencies. A planner agent does this work. The planner can use a frontier model without making the entire run expensive, because the costly reasoning is concentrated in the up-front plan and execution can move to cheaper workers. I am also working on ways to batch planning across multiple Notes.
Dispatch — The act of sending a grounded Note to a dedicated runner for execution.
High-complexity tier — Frontier models such as Claude Opus and GPT-5.6. I reserve these for the hardest work, especially planning and tasks where deep reasoning matters. Claude Fable 5 previously sat in this tier but is currently unavailable.
Medium-complexity tier — Kimi K3 and GLM-5.3. These handle work that benefits from stronger reasoning but does not justify a frontier model.
Low-complexity tier — Kimi K2.7 Code, DeepSeek V4 Pro, and MiniMax M3. These handle simpler, well-scoped tasks where a good plan has already done most of the heavy reasoning.
Yesod model reports: Claude Opus 5, GPT-5.6 Sol, Claude Fable 5, Kimi K3, Kimi K2.7 Code, DeepSeek V4 Pro, and MiniMax M3.
Roles — Agents in the factory require different roles. These include at least a point of contact, an infrastructure monitor, a merge manager, planners, dispatchers, workers, and a few more. In Yesod today, these include the mayor, planner, dispatcher, worker, refinery, infrastructure monitor, triage agent, mad scientist, and ephemeral refinery supervisor.
Theses and Research Questions to Test with Yesod
Each working hypothesis below has its own Open Research Question. The essay states the initial theory; the linked page is the durable record for experiments, evidence, reversals, and decisions as Yesod evolves.
What are the tradeoffs between planning and execution in terms of cost, time, and quality?
Can cheaper models, given a detailed plan and targeted supervision, match frontier models on well-scoped execution tasks? I want Yesod to test this rather than assume it. The comparison needs to hold task shape, instructions, tools, verification, and retry policy constant, then measure delivery rate, review burden, latency, and total cost—not merely whether the first attempt passes. My working hypothesis is that planning and ambiguity resolution benefit most from frontier models, while routine execution can often move down the cost curve once the work has been grounded.
When should expensive models plan and supervise work executed by cheaper models?
How far does this hold? Which parts of planning actually require an expensive model, and which parts can be handled by a cheaper one?
How accurate can complexity estimation get?
Yesod estimates complexity only after a Note has been grounded into an executable plan. The current scale—Easy, Medium, or Advanced—is deliberately coarse. The question is whether that signal can become reliably calibrated. Can the Note, acceptance criteria, Bead tree, affected code, and repository history predict execution difficulty well enough to choose the least expensive model that can reliably complete the work?
I want to measure this against outcomes, not impressions: tokens, wall time, retries, rework, gate failures, and review burden. An estimate is useful only if it improves a real decision. Can it distinguish work that genuinely requires frontier reasoning from work that a cheaper model can handle? How much does accuracy depend on the repository, task type, planner quality, or execution model? My hypothesis is that a coarse estimate can become useful for routing long before it becomes precise enough to predict exact cost or duration.
Does a software factory need multiple focused AI agents to run well?
Gas Town introduced the idea of a “mayor” for a factory: a single point-of-contact agent that knew how to operate it. It also had dispatchers, polecats, a deacon, “dogs,” and other agents. It was an interesting idea, but it often produced a lot of chatter. Yesod currently uses a Mayor agent and planner agents, and I have experimented with a supervisor agent to fix merge issues. The questions are: What is the optimal set of agents? What roles should they play? Should they be ephemeral or long-lived?
How much agent-to-agent communication is actually necessary?
Claude Code agent teams can be an enormous token hog. Anthropic’s own documentation says, “Agent teams add coordination overhead and use significantly more tokens than a single session.”
Can a software factory intelligently choose a model for each dispatch while taking cost into account?
The economics of interacting with CLI harnesses like Claude Code and Codex depend on heavy subsidies that will not exist forever. Make sure the economics of your factory pencil out at API rates, but definitely use the subsidized rates—fixed-cost developer plans—while you can.
Coder plans are here right now, and they are awesome! You can get a lot of value out of them. How do you design dispatch policies that maximize that value? What is the optimal mix of coder plans and straight API rates? Is the ideal outcome to end a usage cycle with 99.9% of your credits used? What useful things can you do with excess inference capacity that would benefit you in the future?
How should a software factory respond to changing prices and batch pricing?
OpenAI has discounted Sol for a limited time. OpenRouter occasionally offers discounts of up to 75%, for example, for Gemini 3.7 Flash and GPT-5.6 Sol Pro. What do you do with this? Imagine a low-priority backlog and dispatch logic that says, “If a frontier model is available for less than $X per token, dispatch these tasks.” How much work would it take to build this? Should I build a pricing agent that scours announcements for cheap inference?
How decoupled can the agents be in a software factory?
It is easy to think up role after role: process janitors, watchers, testers, checkers, and so on. How many of these need to exist? How much do they need to communicate with each other? If they do need to coordinate, is that a good thing, or is it an anti-pattern?
How ephemeral can the agents be?
Should they be always on, with the associated token churn, or ephemeral and enabled in response to certain events? For example, I experimented with a “Refinery Supervisor Agent,” but it created too much churn. One major development was rewriting the refinery system so that it requires agents only when stuck.
How do I enable introspection and long-term learning?
Questions the system should be able to repeatedly ask of itself:
- Which models are good for what?
- I have a macOS runner and three Linux runners. What jobs should be dispatched where?
- What is the value of building test suites?
- How much planning is necessary for a good result?
- When planning, do you plan toward a specific model, toward a model level, or is planning completely general?
What configuration is necessary for maximum productivity?
This is one of the main questions. I am very open to the shape Yesod takes, and there seems to be an eternal tension between “just let agents do everything” and “have a very rigid structure with agents doing highly focused jobs.” I lean more toward the rigid structure side, but this leads to a large amount of code being written, whereas agents are much more flexible.
What can be done locally?
I’ve spent a big part of my career in the cloud, and obviously I love it. At the same time, being able to do things locally has its own benefit. Right now, a cluster of DGX Sparks can run GLM 5.2. How powerful a software factory could you build if you wanted it to be air-gapped? If you have a DGX Spark cluster that is slow but always moving work forward, how much can you get done? What would be the right use of an unlimited near-frontier model? Should it drive the factory and optimize dispatch? More broadly, what is the right mix of local and cloud inference? Local models may be best for private, continuous work with predictable marginal cost, while cloud models can provide burst capacity or capabilities the local cluster cannot match. Where should Yesod draw that boundary, and how should it move as hardware, model quality, latency, and API prices change? What is possible in an air-gapped, local-only scenario?
What happens when you give models a rich “playground” of CPUs, Proxmox, test data, etc.?
Today, the factory’s confidence still comes largely from test suites. Yesod alone has more than 6,500 tests, and its full suite currently runs inside a Lambda MicroVM. I am procuring a Dell PowerEdge R740xd to become the factory’s local compute core—not merely to make the same test run faster, but to give agents room to create disposable environments, run competing implementations in parallel, reproduce failures, generate test data, and try experiments without contending for a narrow shared runner.
That raises a more interesting resource-allocation question: how much CPU, memory, storage, and isolation should an agent receive, and when? If abundant local compute is cheap, will agents spend it productively on stronger verification and exploration, or simply generate more work and noise? I want Yesod to learn which task types benefit from a rich playground, which should remain constrained, and whether the right unit of provisioning is a runner, a Note, a Bead, or an experiment.
How can I facilitate the best environment for agentic programming?
Given excess local compute and potentially excess inference, what can I do to prepare the environment for future agents? For example, the “Yesod ask” system allows agents to interrogate a codebase in natural language: “Where in the code does complexity estimation happen?” Right now, this is powered by simple vector search, but I am planning to experiment with Neo4j Agent Memory, Hindsight, and a couple of other memory systems so that Yesod is always ready to answer questions about the codebases under management. The extra CPU power will make this possible.
Additionally, I save EVERYTHING for later analysis: what I say to the mayor, what the runners do, and both their successful and failed runs. That record can help future agents work more efficiently. I can analyze where earlier agents spent time—for example, which facts they repeatedly searched for, which parts of a codebase took the longest to understand, and which dead ends they explored—then make that knowledge easier for the next agent to retrieve. “Vibe coding” tends to throw away much of this learning-process data. That may be acceptable for small codebases, but in large ones it means spending tokens to rediscover the same lessons again and again. How can I build a rich meta-environment in which agents can become effective in complex codebases without repeatedly paying the same exploration cost?
How far can the human be removed from the loop, and what does that look like?
In the ideal case, I want to be able to propose features—or have agents propose them—and hand those ideas to a process that decides whether they are worth building, where they belong in the ecosystem, and how they should be implemented. That evaluation step matters: indiscriminately accepting every plausible feature produces the Homer, a product assembled from individually appealing ideas without a coherent whole. If Yesod can supply that product judgment and return implementations ready for me to test, how far can the human role shift from supervising execution to setting direction? What would that change about the pace, economics, and range of software creation? More generally, what is the shape and mechanism of a creative process that combines AI and human input?
Where is this going?
Right now, I feel a little like a caveman seeing fire for the first time. I’m using it for warmth and cooking, heating rocks to see what happens, and slowly learning what it can do. I do not know exactly where this leads, but I have a hunch that we will eventually need something closer to a steel mill than a campfire. Yesod is my attempt to start building toward that.
Footnotes
-
Years in the AWS ecosystem taught me how useful it is when an identifier reveals the kind of object it names. An EC2 instance ID such as
i-0abcdef1234567890is recognizable before you look it up. Yesod follows the same principle: theys-prefix marks a Yesod Note, andyesidentifies the tool it belongs to. ↩