Millworks
A transparent, persona-driven workflow harness for AI coding agents. Millworks
runs on two surfaces over one shared core — natively on
pi.dev, and as a Claude Code plugin — so the same workflows,
personas, and visible subagents work in either agent.
Millworks treats software work — bug fixing, refactoring, investigation,
greenfield builds, audits, reviews — as shaped work running through pluggable
workflows with competing personas and full human visibility into every
subagent.
What Millworks is opinionated about
- No black-box subagents. Every dispatched agent runs in a real
tmux
pane the user can attach to, watch, steer, or close. Visibility is the
premise, not an afterthought — on both surfaces (pi.dev spawns pi, Claude
Code spawns claude, both into visible panes).
- Workflow-shape follows work-shape. Bug fixes, refactors, audits, and
greenfield builds use different workflow templates from a shared library.
The harness doesn't impose one shape.
- Database-source-of-truth for project state. Project tasks, dependencies,
decisions, and — uniquely — workflow run state live in
beads (Dolt-backed graph store). A run
is reconstructed from beads and survives a restart: kill the host mid-run,
relaunch, and it recovers the active run, reconciles step state against live
panes, and resumes. Markdown views are derived, not hand-edited.
- Thin glue, heavy Rust CLIs. The surface adapters (pi.dev extensions, the
Claude MCP server) are wrappers over CLI tools —
tmux, bd, and our own Rust
binaries. Real logic lives in independently testable command-line programs, so
both surfaces share it byte-for-byte.
- Competing personas. Multiple agent files can claim the same role
(
debugger-systematic.md, debugger-bisect-first.md); the harness picks
based on routing metadata and (eventually) historical performance.
Status
Phase 14 (the Claude Code surface) is complete. Millworks now ships on both
surfaces at parity: beads is the canonical, restart-recoverable run store on each,
and the persisted run-state schema is unified — a run started on either surface is
recoverable by the other.
7 workflow templates, 20 personas, a shared Rust core (4 focused CLIs +
the millworks unified CLI), 3 pi.dev extensions, and the Claude Code plugin
(13 /millworks:* commands + a bundled MCP server). Dogfooded: the
greenfield-compile workflow ran on a real project (lmcq — a Rust telemetry
processing system).
Quick Start
Install once (builds the shared Rust core), then pick your surface.
pi.dev
# 1. Install (pi.dev surface)
curl -fsSL https://raw.githubusercontent.com/Liquescent-Development/millworks/main/install.sh | bash
# 2. Initialize a project
cd your-project
millworks init
# 3. Start coding with pi
pi
Inside pi:
/workflow-list — browse available workflow templates/workflow-run bug-fix "login form returns 500" — run a workflow/prime — full beads project view
Claude Code
# 1. Install with the Claude Code plugin (adds --claude)
curl -fsSL https://raw.githubusercontent.com/Liquescent-Development/millworks/main/install.sh | bash -s -- --claude
The installer assembles the plugin and prints the one-time registration
commands. In a Claude Code session (started inside tmux, so subagents are
visible):
/plugin marketplace add ~/.local/share/millworks
/plugin install millworks@millworks
Then, in a project:
/millworks:init — initialize the project for Millworks (beads + run-tracking types)/millworks:workflows — list the available workflows/millworks:run-workflow bug-fix "login form returns 500" — run one by name- Or just describe the work ("fix this bug", "audit the dependencies") — a skill
recommends the matching workflow and asks before running it
Gates surface as a native Approve / Reject / Skip menu (with
/millworks:gate-* commands as a typed fallback).
Prerequisites
git, cargo (Rust toolchain), node + npm, tmux, and bd (beads) for
both surfaces; plus pi for the pi.dev surface or claude (the Claude Code CLI)
for the Claude surface. The installer checks for these and prints install
instructions if any are missing.
Full install docs — including the manual path, the Claude registration details,
and refreshing after a rebuild — are in docs/INSTALLING.md.
Repo layout
