programmatic subagents
docs: add README.md
+128
+128
README.md
+128
README.md
···
1
+
# mill
2
+
3
+
A runtime for executing TypeScript programs that spawn and coordinate AI agents. Write plain TS with `await` and `Promise.all` — mill handles the lifecycle, persistence, and observability.
4
+
5
+
## What you can do
6
+
7
+
**Orchestrate agents in plain TypeScript** — no DSL, no YAML, just sequential and parallel `await` calls with a single injected `mill.spawn()` API.
8
+
9
+
**Run async by default** — `mill run` returns a `runId` immediately and executes in a detached worker. Attach later with `watch`, `wait`, or `inspect`.
10
+
11
+
**Swap agent backends** — drivers are generic adapters. Ship with pi, Claude, and Codex drivers. Write your own by implementing a codec that parses process output into structured events.
12
+
13
+
**Observe everything** — structured NDJSON event log per run, real-time streaming via `mill watch`, and full session replay via `mill inspect --session`.
14
+
15
+
## Quick example
16
+
17
+
```ts
18
+
// review.ts
19
+
const scan = await mill.spawn({
20
+
agent: "scout",
21
+
systemPrompt: "You are a code risk analyst.",
22
+
prompt: "Review src/auth and summarize top security risks.",
23
+
model: "openai/gpt-5.3-codex",
24
+
});
25
+
26
+
const plan = await mill.spawn({
27
+
agent: "planner",
28
+
systemPrompt: "You turn findings into an execution-ready plan.",
29
+
prompt: `Create remediation steps from:\n\n${scan.text}`,
30
+
});
31
+
32
+
console.log(plan.text);
33
+
```
34
+
35
+
```bash
36
+
mill run review.ts # returns runId, executes in background
37
+
mill watch abc123 # stream events live
38
+
mill run review.ts --sync # or block until done
39
+
```
40
+
41
+
## CLI
42
+
43
+
```
44
+
mill run <program.ts> [--sync] [--json] [--driver <name>]
45
+
mill status <runId> show run state
46
+
mill wait <runId> --timeout block until complete/failed/cancelled
47
+
mill watch <runId> stream tier-1 events (NDJSON with --json)
48
+
mill inspect <id>[.<spawnId>] inspect run or spawn detail
49
+
mill inspect <id> --session resolve full agent session via driver
50
+
mill cancel <runId> interrupt run and all live spawns
51
+
mill ls [--status <filter>] list runs
52
+
mill init generate starter mill.config.ts
53
+
```
54
+
55
+
All commands accept `--json` for machine-readable output on stdout (diagnostics go to stderr).
56
+
57
+
## Configuration
58
+
59
+
```ts
60
+
// mill.config.ts
61
+
import { defineConfig, processDriver, piCodec } from "@mill/core";
62
+
63
+
export default defineConfig({
64
+
defaultDriver: "pi",
65
+
defaultModel: "openai/gpt-5.3-codex",
66
+
defaultExecutor: "direct",
67
+
drivers: {
68
+
pi: processDriver({
69
+
command: "pi",
70
+
args: ["-p"],
71
+
codec: piCodec(),
72
+
}),
73
+
},
74
+
});
75
+
```
76
+
77
+
Resolved in order: `./mill.config.ts` → walk up to repo root → `~/.mill/config.ts` → built-in defaults.
78
+
79
+
## Packages
80
+
81
+
| Package | Purpose |
82
+
|---|---|
83
+
| `@mill/core` | Engine, run lifecycle, public API, config loader |
84
+
| `@mill/cli` | CLI commands wrapping core |
85
+
| `@mill/driver-pi` | Process driver for pi agent |
86
+
| `@mill/driver-claude` | Driver for Claude |
87
+
| `@mill/driver-codex` | Driver for Codex |
88
+
| `@mill/pi-mill` | Pi extension integrating mill as execution backend |
89
+
90
+
## Architecture
91
+
92
+
```
93
+
mill program (TS)
94
+
→ executor (direct | vm)
95
+
→ engine (lifecycle, API injection, events, persistence)
96
+
→ driver (generic process/http adapter + codec)
97
+
→ agent process
98
+
```
99
+
100
+
Layers are orthogonal: executor decides *where* the program runs, driver decides *how* spawns invoke agents, extensions add hooks and extra API surface.
101
+
102
+
### Run storage
103
+
104
+
```
105
+
~/.mill/runs/<runId>/
106
+
run.json metadata
107
+
events.ndjson append-only structured event log
108
+
result.json final output
109
+
program.ts copied source
110
+
```
111
+
112
+
### Internals
113
+
114
+
Built on [Effect](https://effect.website). The public API (`src/public/**/*.api.ts`) exposes Promise-based contracts. Everything else — engine, drivers, persistence — is Effect-first with Schema-validated domain types. `Runtime.runPromise` is the only bridge between the two worlds.
115
+
116
+
## Development
117
+
118
+
```bash
119
+
bun install
120
+
bun test # run tests
121
+
bun run check # full pipeline: ast-grep + lint + format + typecheck + test
122
+
bun run typecheck # tsgo --noEmit
123
+
bun run lint:ast-grep # structural guardrails
124
+
bun run lint:boundary # public/internal boundary enforcement
125
+
bun run format # oxfmt
126
+
```
127
+
128
+
Toolchain: ast-grep (structural rules), oxlint, oxfmt, tsgo, bun test.