bldr

A lightweight, language-agnostic build daemon that exposes your project's build flows as MCP (Model Context Protocol) tools, letting an AI assistant like Claude drive builds, check status, and react to results without any project-specific plumbing.

Homepage: bldr-ecbf6d.gitlab.io (Next.js site in site/, built by bldr itself via bldr --project site/bldr.toml --flow build and published to GitLab Pages by .gitlab-ci.yml)

---

What it does

• Runs as a single long-lived process managing one or more projects.
• Each project is described by a bldr.toml that declares stages, flows, and optional capability plugins.
• Stages are shell commands; flows are ordered lists of stages.
• The daemon exposes FastMCP tools so an MCP client can trigger and monitor builds, manage worktrees, and invoke plugin actions.
• State is persisted in SQLite (XDG data dir) so build history survives restarts. Any record that was "running" at restart is marked "interrupted" -- the daemon never reports stale in-progress state.
• Per-project async locks mean projects build concurrently without stepping on each other.
• Projects can be added and removed at runtime via add_project / remove_project.

---

Architecture

                       one daemon, many projects
  MCP client (Claude) --> FastMCP tools (project-routed) --> ProjectRegistry
                                     |                            |
                               /status endpoint            per-project:
                               (GET, JSON)                 ProjectState + Lock
                                                           pipeline (flow runner)
                                                           runner (async shell)
                                                           plugins (Capabilities)
                                                                  |
                                                           SQLite (XDG data dir)

---

Concepts

Stages

A stage is a named shell command declared in [stages.<name>]:

Field	Default	Description
cmd	(required)	Shell command to run. Supports {{message}}, {{branch}}, {{project_root}} templates.
cwd	project root	Override working directory for this stage only.
interruptible	true	If false, a new build request queues behind this stage rather than cancelling it.
timeout	none	Max seconds before the stage is killed.

Flows

A flow is an ordered list of stage names. When request_build is called:

• If nothing is running, the flow starts immediately.
• If the current stage is interruptible, the running flow is cancelled and the new flow starts.
• If the current stage is non-interruptible, the new request is queued and starts as soon as that stage finishes.

Plugins (Capabilities)

A plugin is a Python Capability subclass registered under [plugins.<key>] in bldr.toml. Plugins can:

• Start and stop background services (start() / stop()).
• Contribute named stage handlers used inside flows.
• Register MCP tools available to the AI client.

Worktrees

Worktrees are parallel isolated builds of the same project, backed by Git worktrees. Each worktree appears in the registry as <project>::<name> and gets its own plugin instances (with ephemeral ports to avoid conflicts).

---

MCP Tools

All project-scoped tools require a project argument (the value of name in [project]). There is no single-project mode; projects are always addressed by name.

Core tools

Tool	Arguments	Description
list_projects	--	List all registered projects with their flows and status.
request_build	project, flow, message=""	Start, queue, or restart a flow. Returns started, queued, or restarted.
get_status	project	Return current status, running stage, recent log lines, and build history.
add_project	config_path	Register a new project from a bldr.toml path. Starts its plugins.
remove_project	project	Unregister a project, cancel any running flow, stop its plugins.

Worktree tools

Tool	Arguments	Description
create_worktree	project, name, branch=""	Create a Git worktree of project, register it as project::name.
list_worktrees	project	List all registered worktrees for a project.
build_worktree	project, name, flow, message=""	Run a flow on a worktree (project::name).
remove_worktree	project, name	Cancel the worktree's flow, stop its plugins, and remove the Git worktree.

Plugin tools

These tools are registered by their respective plugins and are only available when the project declares that plugin in its bldr.toml.

Tool	Plugin	Arguments	Description
list_artifacts	artifact_http	project	List files currently in the artifacts directory.
serve	web_serve	project	(Re)start the web server and return its URLs.
screenshot_build	screenshot	project, url, wait_seconds=3.0, width=0, height=0	Capture a headless screenshot and save it to out_dir.
compare_screenshot	screenshot	project, url, baseline_name, save_baseline=False, diff_threshold=None, wait_seconds=3.0, width=0, height=0	Compare a live screenshot to a saved baseline; returns match/mismatch and diff percent.
request_demo_deploy	demo_deploy	project, push=False	Copy the build dir into a target git repo, patch index.html, commit, and optionally push.

---

Configuration

Each project requires a bldr.toml. All paths are resolved relative to the config file unless absolute.

[project]
name = "my-app"
# root defaults to the directory containing bldr.toml.
root = "."

# Flows are ordered lists of stage names.
[flows]
build   = ["clean", "compile", "package"]
test    = ["clean", "compile", "test_suite"]
release = ["clean", "compile", "package", "artifact_publish"]

# Each stage must have a cmd. Other fields are optional.
[stages.clean]
cmd           = "rm -rf build dist"
interruptible = true        # default

[stages.compile]
cmd           = "make -j4"
interruptible = false       # queues new requests until this stage finishes
timeout       = 120         # seconds; omit to disable

[stages.package]
cmd           = "make dist"

[stages.test_suite]
cmd           = "pytest -q"
timeout       = 300
# cwd = "../other-dir"   # per-stage working directory override

# -- Plugins --

# artifact_http: copy build outputs to a served directory.
# Adds an "artifact_publish" stage handler and a "list_artifacts" MCP tool.
[plugins.artifact_http]
dir       = "artifacts"              # relative to project root
port      = 9099                     # 0 = ephemeral port
bind      = ["127.0.0.1"]
keep      = 10                       # prune oldest beyond this count
artifacts = ["build/my-app.tar.gz", "build/index.html"]

# web_serve: serve a build directory with Cache-Control: no-store.
# Adds a "serve" MCP tool.
[plugins.web_serve]
build_dir = "build"
port      = 8100
bind      = ["127.0.0.1"]

# screenshot: headless-browser screenshots via Playwright.
# Adds "screenshot_build" and "compare_screenshot" MCP tools.
[plugins.screenshot]
viewport       = [412, 915]   # [width, height] in pixels (default)
out_dir        = "screenshots"
diff_threshold = 0.01         # fraction of changed pixels to count as mismatch
noise          = 30           # per-channel delta below which a pixel is "same"

# demo_deploy: copy a build directory into a target git repo and commit.
# Adds a "demo_deploy" stage handler and a "request_demo_deploy" MCP tool.
[plugins.demo_deploy]
build_dir         = "build"
target_repo       = "/path/to/pages-repo"
target_subdir     = "."           # subdirectory inside target_repo
base_href         = "/my-app/"    # patches <base href> in index.html
page_title        = "My App"      # patches <title>
page_description  = "My demo"     # patches <meta name="description">
commit_message    = "Deploy demo via bldr"
branch            = "main"

Key rules:

• Every stage name referenced in a flow must have a [stages.<name>] entry OR be provided by a plugin's stage_handlers().
• An unknown or broken plugin is logged and skipped; it does not crash the daemon.

---

Built-in Plugins

artifact_http

Copies matched glob patterns from the project root into a served directory, renames each by the name template, prunes the oldest files beyond keep, and serves the directory over plain HTTP (with no index.html, the default Python http.server directory listing). Bind it to a LAN/VPN address and any machine can browse the directory and download artifacts.

Option	Default	Description
dir	"artifacts"	Directory to publish into (relative to project root).
port	9099	TCP port; 0 picks a free ephemeral port.
bind	["127.0.0.1"]	Addresses to bind (a down interface is skipped).
keep	10	Max files to retain (oldest pruned); 0 keeps everything.
name	"{name}"	Filename template for published artifacts (see below).
artifacts	[]	Glob patterns (relative to project root) to copy on artifact_publish.

The name template builds each published filename from these placeholders: {name} (original basename), {stem}, {ext} (incl. the dot), {project}, {branch} (sanitized), {sha} (short git hash), {ts} (YYYYMMDD-HHMMSS). The default "{name}" keeps the basename (each build overwrites the last). A template like "{project}-{branch}-{ts}-{sha}{ext}" makes every build a distinct file, so the whole build history accumulates and stays browsable over HTTP (bounded by keep). Different artifact kinds (e.g. .apk and .aab) are kept apart by {ext}. The git branch/sha are read from the project root, so a worktree publishes under its own branch.

Stage handler: artifact_publish -- copies + renames matching files, logs their URLs. MCP tool: list_artifacts(project) -- returns sorted filenames in the directory.

web_serve

Serves a build directory with Cache-Control: no-store so browsers always fetch the latest build. Restarts the server each time the serve tool is called.

Option	Default	Description
build_dir	"build"	Directory to serve (relative to project root).
port	8100	TCP port.
bind	["127.0.0.1"]	List of addresses to bind.

MCP tool: serve(project) -- restarts the server and returns its URL(s).

screenshot

Uses Playwright (Chromium, headless) to capture screenshots and run pixel-diff regression checks. Requires playwright and Pillow to be installed.

Option	Default	Description
viewport	[412, 915]	[width, height] in pixels.
out_dir	"screenshots"	Directory for captured PNGs. Baselines go in out_dir/baselines/.
diff_threshold	0.01	Fraction of pixels that may differ before a comparison is "mismatch".
noise	30	Per-channel delta (0-255) below which a pixel is considered unchanged.

MCP tools:

• screenshot_build(project, url, wait_seconds, width, height) -- captures and saves a PNG.
• compare_screenshot(project, url, baseline_name, save_baseline, diff_threshold, wait_seconds, width, height) -- compares to a saved baseline; saves a diff image on mismatch.

demo_deploy

Copies a build directory into a separate git repository (e.g. a GitLab Pages repo), optionally patches index.html (base href, title, description), commits the change, and optionally pushes.

Option	Default	Description
build_dir	"build"	Source directory (relative to project root).
target_repo	""	Absolute path to the target git repository.
target_subdir	"."	Subdirectory inside target_repo to deploy into.
base_href	none	Replaces <base href="..."> in index.html.
page_title	none	Replaces <title> in index.html.
page_description	none	Replaces <meta name="description"> in index.html.
commit_message	"Deploy demo via bldr"	Git commit message.
branch	"main"	Branch to push to when push=True.

Stage handler: demo_deploy -- deploys without pushing (commit only). MCP tool: request_demo_deploy(project, push=False) -- deploy on demand; set push=True to also push to the remote.

Security note: artifact_http and web_serve are unauthenticated static file servers. They default to loopback (127.0.0.1). Setting a non-loopback bind address (e.g. 0.0.0.0) exposes served files to anyone on the network -- use that option only on trusted networks.

---

Plugin authoring

Subclass Capability, implement the hooks you need, then call register_capability with an optional module-level tool registrar.

from bldr.plugins.base import Capability, register_capability


class MyPlugin(Capability):
    name = "my_plugin"

    def __init__(self, project_config, options: dict):
        super().__init__(project_config, options)
        # project_config.root is the absolute path to the project directory.
        # options is the dict from [plugins.my_plugin] in bldr.toml.
        self.port = int(options.get("port", 8080))

    async def start(self) -> None:
        # Start a background service (e.g. an HTTP server). Optional.
        pass

    async def stop(self) -> None:
        # Tear down the background service. Optional.
        pass

    def stage_handlers(self) -> dict:
        # Return a mapping of stage name -> async callable.
        # The pipeline calls: await handler(registered_project, build_record)
        async def my_stage(rp, rec) -> None:
            rp.state.log("running my_stage")
        return {"my_stage": my_stage}


def register_tools(mcp, lookup):
    # MCP tools are registered once per plugin TYPE, not per project instance.
    # Use lookup(project, "my_plugin") to resolve the per-project capability.
    @mcp.tool()
    async def my_tool(project: str) -> dict:
        cap = lookup(project, "my_plugin")
        if cap is None:
            return {"error": f"project '{project}' has no my_plugin"}
        return {"port": cap.port}


register_capability("my_plugin", MyPlugin, register_tools)

The register_tools(mcp, lookup) function is called once at daemon startup. The lookup(project, cap_name) helper resolves the named capability for any registered project. Tool names must be globally unique across all plugins.

---

Running

# Start with one project pre-loaded
bldr --project path/to/bldr.toml

# Start with multiple projects
bldr --project proj-a/bldr.toml --project proj-b/bldr.toml

# Start empty; add projects via the add_project MCP tool at runtime
bldr

# Custom host/port (default: 127.0.0.1:7900)
bldr --host 0.0.0.0 --port 8000 --project bldr.toml

The --project flag is repeatable and optional. Projects can also be registered and removed at runtime via the add_project and remove_project MCP tools.

TUI monitor

bldr-tui is a live, interactive monitor (Textual). It polls the daemon's /status endpoint and shows a multi-pane view for the selected project:

• a status bar (stage icon/color, current message, elapsed time, pending),
• a streaming build log and web-server log,
• a projects/worktrees pane (status, port, branch, commit; worktrees nested under their parent),
• a build-history pane.

bldr-tui                          # connects to http://127.0.0.1:7900
bldr-tui --url http://host:8000   # custom daemon address

Keys: j/k select project/worktree, b build (prompts for flow), w new worktree, d remove worktree, r refresh, c clear, n toggle desktop notifications, a toggle browser auto-reload (reloads pages of a Chrome started with --remote-debugging-port=9222 when a build finishes), R reload now, q quit. Actions are performed over MCP. Requires textual (a dependency); the view refreshes every 1.5 s.

CLI client (bldr-cli)

bldr-cli is a command-line client for the daemon's MCP tools: each tool is a subcommand, positional args fill the tool's parameters in schema order, key=value sets a named one, and values are JSON-coerced (numbers, booleans, null, arrays, objects). Output is pretty-printed JSON; pass -j/--json for compact single-line output.

bldr-cli --help                         # usage + all tools + aliases
bldr-cli tools                          # list tools and their parameters
bldr-cli ls                             # list_projects
bldr-cli st kairos                      # get_status kairos (pretty)
bldr-cli build kairos web               # request_build project=kairos flow=web
bldr-cli request_demo_deploy kairos push=true
bldr-cli screenshot_build kairos http://127.0.0.1:8010
bldr-cli -j ls                          # compact JSON (scripting)

Aliases: ls=list_projects, st/status=get_status, build=request_build, add=add_project, rm=remove_project. The daemon URL defaults to $BLDR_URL or http://127.0.0.1:7900/mcp (override with --url).

Status endpoint

GET /status on the daemon returns a JSON snapshot of all projects -- the same data the TUI polls. Useful for scripting or health checks.

---

Bundled example

example-project/ exercises the full pipeline without any external toolchain:

example-project/
  bldr.toml        # build + release flows, artifact_http plugin
  build.sh         # copies site/ into build/
  site/
    index.html

Flows:

• build -- runs clean then build_site (produces build/index.html).
• release -- runs clean, build_site, then artifact_publish (copies the file into artifacts/ and serves it over HTTP on an ephemeral port).

cd example-project
bldr --project bldr.toml
# then call request_build("example-site", "release", "manual test") via MCP

---

Testing

pip install -e ".[dev]"
pytest

70 tests covering the pipeline, registry, plugins, worktrees, CLI, TUI, and end-to-end integration.