milhouse 1.0.1

package/AGENTS.md

@@ -0,0 +1,49 @@
+# Repository Guidelines
+
+## Project Structure
+
+- `src/cli.ts`: npm-installed CLI entrypoint (`milhouse`) with the yellow header.
+- `ui/server.ts`: Express server for the local web UI; static assets live in `ui/public/` (copied to `dist/ui/public/` on build).
+- `src/loop-runner.ts`: Node-based loop engine used by the UI (plan once, then iterate until `STATUS: DONE`).
+- `prompts/*.md`: Prompt templates used by the loop runner (interpolate `{{GOAL}}` and `{{PLAN_PATH}}`).
+- `dist/`: Compiled output (generated; not committed).
+
+## Build, Test, and Development Commands
+
+Prereqs: Node.js 18+.
+
+```bash
+npm install            # install deps
+npm run typecheck      # tsc --noEmit
+npm run build          # compile to dist/ and copy UI assets
+npm run ui             # build + start web UI (local-only)
+npm run dev -- ui      # run UI from TS via tsx
+```
+
+Installed usage (after publish):
+```bash
+npm install -g milhouse
+milhouse ui
+```
+
+## Coding Style & Naming Conventions
+
+- TypeScript ESM (NodeNext) with `strict` enabled.
+- Match existing formatting: 2-space indentation, semicolons, double quotes.
+- CLI flags use kebab-case (`--state-dir`, `--workdir`).
+
+## Testing Guidelines
+
+- No dedicated test suite yet. Validate with:
+  - `npm run typecheck`
+  - `npm run ui` and verify start/stop + live logs/artifacts
+
+## Commit & Pull Request Guidelines
+
+- Use Conventional Commits (`feat:`, `fix:`, `docs:`), e.g. `feat(ui): ...`.
+- PRs should include: summary, local verification steps, and screenshots for UI changes.
+
+## Security & Configuration Tips
+
+- Never commit secrets. `CODEX_API_KEY` is optional (can fall back to local Codex auth if configured).
+- State/logs default to the OS user data directory; override with `MILHOUSE_STATE_DIR` or `milhouse ui --state-dir <path>`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Milhouse Van Houten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# Milhouse Van Houten
+
+![Milhouse](milhouse.png)
+
+Milhouse Van Houten is a chad pair programmer that provides a lightweight web UI for running Codex threads, starting with a quick planning phase and iterating through builds until the job is done. Inspired by a Ralph Wiggum-style autonomous loop, Milhouse focuses on simplicity, approachability, and making experimentation fun and easy to modify.
+
+This repository contains the **bare-bones** version of Milhouse. It represents the core foundation, with many new features, experiments, and feedback loops currently in the pipeline.
+
+## Features
+
+* Web UI for managing Codex runs
+* Ralph Wiggum-style autonomous loop system: plan once, then iterate builds until done
+* Live logs via Server-Sent Events (SSE)
+* Session history with status tracking
+* Cross-platform folder picker (Windows, macOS, Linux)
+
+## Prerequisites
+
+* Node.js 18+
+* `CODEX_API_KEY` set in your environment **(optional if your Codex CLI is already authenticated)**
+
+## Install
+
+```bash
+npm install -g milhouse
+```
+
+## Usage
+
+Start the Web UI:
+
+```bash
+milhouse ui
+```
+
+This opens a local web panel at `http://127.0.0.1:4173` (falls back to a free port if busy).
+
+### CLI Options
+
+```text
+milhouse ui [OPTIONS]
+
+Options:
+  --host <ip>           Server host (default: 127.0.0.1)
+  --port <n>, -p <n>    Server port (default: 4173)
+  --workdir <path>, -w  Working directory for Codex (default: current directory)
+  --state-dir <path>    State/logs directory (default: OS user data directory)
+  --no-open             Don't auto-open browser
+  --help, -h            Show help
+```
+
+### Examples
+
+```bash
+# Start with default settings
+milhouse ui
+
+# Specify a project directory
+milhouse ui --workdir /path/to/project
+
+# Use a custom port
+milhouse ui --port 8080
+
+# Don't auto-open browser
+milhouse ui --no-open
+```
+
+## How It Works
+
+1. **Plan Phase**: Enter a goal in the Web UI. Milhouse generates an `IMPLEMENTATION_PLAN.md` with prioritized tasks.
+2. **Build Loop**: Milhouse iteratively executes tasks from the plan, updating progress after each iteration.
+3. **Completion**: When all tasks are done, the plan is marked `STATUS: DONE` and the loop exits.
+
+## Web UI Features
+
+* **Hero Status**: Shows current run status and thread ID
+* **Controls**: Start/stop runs, set goals and max iterations
+* **Live Logs**: Real-time log streaming with auto-scroll
+* **Artifacts**: View plan output, build logs, and implementation plan
+* **Sessions**: History of all runs with status, timestamps, and durations
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/ordinalOS/Milhouse-Van-Houten.git
+cd Milhouse-Van-Houten
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev -- ui
+
+# Build for production
+npm run build
+
+# Run built version
+npm run ui
+```
+
+## Environment Variables
+
+* `CODEX_API_KEY`: OpenAI Codex API key (optional if using local Codex auth)
+* `MILHOUSE_STATE_DIR`: Override default state directory
+* `MILHOUSE_DEFAULT_WORKDIR`: Override default working directory
+
+(Legacy env vars `MILLHOUSE_STATE_DIR` / `MILLHOUSE_DEFAULT_WORKDIR` are still supported.)
+
+## How to Contribute
+
+Thank you for considering contributing to Milhouse! This repository is intentionally open-ended, and we welcome contributions of all kinds — including bug fixes, enhancements, documentation improvements, new loops, unconventional experiments, and wild ideas.
+
+If you have something you want to try, this is the place to do it. Fork the repository, explore freely, and open a pull request when you’re ready. No idea is a bad idea. Creativity encouraged.
+
+MIT License — see [LICENSE](LICENSE) for details.

package/dist/src/banner.js

@@ -0,0 +1,47 @@
+import figlet from "figlet";
+const ANSI_BRIGHT_YELLOW = "\u001B[93m";
+const TRUECOLOR_YELLOW = "\u001B[38;2;255;255;0m";
+const RESET = "\u001B[0m";
+const BANNER_TEXT = "MILHOUSE";
+const CONTACT_LINE = "github.com/ordinalOS/Milhouse-Van-Houten";
+const SEPARATOR_CHAR = "─";
+function useColor() {
+    return Boolean(process.stdout.isTTY) && process.env.NO_COLOR == null;
+}
+function supportsTruecolor() {
+    const colorterm = process.env.COLORTERM?.toLowerCase();
+    return colorterm === "truecolor" || colorterm === "24bit" || colorterm?.includes("truecolor") === true;
+}
+function rtrim(value) {
+    return value.replace(/\s+$/u, "");
+}
+function maxWidth(lines) {
+    return lines.reduce((acc, line) => Math.max(acc, line.length), 0);
+}
+function makeSeparator(width) {
+    if (width <= 0)
+        return "";
+    return SEPARATOR_CHAR.repeat(width);
+}
+export function getMilhouseHeader() {
+    const bannerLines = figlet
+        .textSync(BANNER_TEXT, { font: "ANSI Shadow" })
+        .trimEnd()
+        .split("\n")
+        .map(rtrim);
+    const allLines = [...bannerLines];
+    const width = maxWidth([...allLines, CONTACT_LINE]);
+    const sep = makeSeparator(width);
+    if (!useColor()) {
+        const combined = allLines.join("\n");
+        return `${combined}\n${sep}\n${CONTACT_LINE}\n${sep}\n`;
+    }
+    const truecolor = supportsTruecolor();
+    const color = truecolor ? TRUECOLOR_YELLOW : ANSI_BRIGHT_YELLOW;
+    const lineColor = color;
+    const coloredLines = allLines.map((line) => `${color}${line}${RESET}`);
+    return `${coloredLines.join("\n")}\n${lineColor}${sep}${RESET}\n${lineColor}${CONTACT_LINE}${RESET}\n${lineColor}${sep}${RESET}\n`;
+}
+export function printMilhouseHeader() {
+    process.stdout.write(getMilhouseHeader());
+}

package/dist/src/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import path from "node:path";
+import open from "open";
+import { printMilhouseHeader } from "./banner.js";
+import { startServer } from "../ui/server.js";
+function printHelp() {
+    const help = [
+        "Usage:",
+        "  milhouse ui [--workdir <path>] [--port <n>] [--host <ip>] [--state-dir <path>] [--no-open]",
+        "",
+        "Examples:",
+        "  milhouse ui --workdir .",
+        "  milhouse ui --port 4173",
+    ];
+    process.stdout.write(`${help.join("\n")}\n`);
+}
+function parseUiOptions(argv) {
+    let host = "127.0.0.1";
+    let port = 4173;
+    let workdir = process.cwd();
+    let stateDir;
+    let openBrowser = true;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--help":
+            case "-h":
+                printHelp();
+                process.exit(0);
+            case "--host": {
+                const value = argv[i + 1];
+                if (!value)
+                    throw new Error("Missing value for --host");
+                host = value;
+                i += 1;
+                break;
+            }
+            case "--port":
+            case "-p": {
+                const value = argv[i + 1];
+                if (!value)
+                    throw new Error("Missing value for --port");
+                port = Number(value);
+                if (!Number.isFinite(port) || port < 0 || port > 65535)
+                    throw new Error(`Invalid port: ${value}`);
+                i += 1;
+                break;
+            }
+            case "--workdir":
+            case "-w": {
+                const value = argv[i + 1];
+                if (!value)
+                    throw new Error("Missing value for --workdir");
+                workdir = path.resolve(value);
+                i += 1;
+                break;
+            }
+            case "--state-dir": {
+                const value = argv[i + 1];
+                if (!value)
+                    throw new Error("Missing value for --state-dir");
+                stateDir = path.resolve(value);
+                i += 1;
+                break;
+            }
+            case "--open":
+                openBrowser = true;
+                break;
+            case "--no-open":
+                openBrowser = false;
+                break;
+            default:
+                throw new Error(`Unknown arg: ${arg}`);
+        }
+    }
+    return { host, port, workdir, stateDir, openBrowser };
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    if (!cmd || cmd === "--help" || cmd === "-h") {
+        printMilhouseHeader();
+        printHelp();
+        return;
+    }
+    if (cmd !== "ui") {
+        printMilhouseHeader();
+        throw new Error(`Unknown command: ${cmd}`);
+    }
+    const options = parseUiOptions(argv.slice(1));
+    printMilhouseHeader();
+    const { url } = await startServer({
+        host: options.host,
+        port: options.port,
+        defaultWorkdir: options.workdir,
+        stateBaseDir: options.stateDir,
+    });
+    process.stdout.write(`Milhouse panel running at ${url}\n`);
+    if (options.openBrowser) {
+        try {
+            await open(url);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`Failed to open browser: ${message}\n`);
+        }
+    }
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+});

package/dist/src/codexRun.js

@@ -0,0 +1,24 @@
+import { Codex } from "@openai/codex-sdk";
+export async function runTurn(options) {
+    const apiKey = process.env.CODEX_API_KEY;
+    const codex = apiKey ? new Codex({ apiKey }) : new Codex();
+    const threadOptions = {
+        workingDirectory: options.workdir,
+        sandboxMode: options.sandboxMode,
+        approvalPolicy: options.approvalPolicy,
+        skipGitRepoCheck: options.skipGitRepoCheck ?? true,
+        additionalDirectories: options.additionalDirectories,
+        networkAccessEnabled: options.networkAccessEnabled,
+        webSearchEnabled: options.webSearchEnabled,
+    };
+    const thread = options.threadId
+        ? codex.resumeThread(options.threadId, threadOptions)
+        : codex.startThread(threadOptions);
+    const turn = await thread.run(options.promptText);
+    return {
+        threadId: thread.id,
+        finalResponse: turn.finalResponse,
+        items: turn.items,
+        usage: turn.usage,
+    };
+}

package/dist/src/index.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { Codex } from "@openai/codex-sdk";
+function printUsage() {
+    const usage = [
+        "Usage: npm run codex -- \"<prompt>\" [--thread <id>] [--workdir <path>] [--json] [--stream] [--log-file <path>]",
+        "   or: npm run codex -- --prompt-file <path> [--thread <id>] [--workdir <path>] [--json] [--stream] [--log-file <path>]",
+        "",
+        "Options:",
+        "      --prompt-file <path>  Read prompt from file",
+        "  -t, --thread <id>   Resume an existing Codex thread",
+        "  -w, --workdir <path> Working directory for the agent (defaults to current)",
+        "      --stream        Stream Codex events to stderr",
+        "      --log-file <path> Write final JSON to a file",
+        "      --json          Print JSON (response, items, usage, threadId)",
+        "  -h, --help          Show this help text",
+    ];
+    console.log(usage.join("\n"));
+}
+function parseArgs(argv) {
+    if (argv.length === 0) {
+        printUsage();
+        process.exit(1);
+    }
+    let threadId;
+    let promptFile;
+    let workdir;
+    let stream = false;
+    let logFile;
+    let json = false;
+    const promptParts = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--prompt-file": {
+                const value = argv[i + 1];
+                if (!value) {
+                    console.error("Missing value for --prompt-file");
+                    process.exit(1);
+                }
+                promptFile = value;
+                i += 1;
+                break;
+            }
+            case "--log-file": {
+                const value = argv[i + 1];
+                if (!value) {
+                    console.error("Missing value for --log-file");
+                    process.exit(1);
+                }
+                logFile = value;
+                i += 1;
+                break;
+            }
+            case "--stream":
+                stream = true;
+                break;
+            case "-t":
+            case "--thread": {
+                const value = argv[i + 1];
+                if (!value) {
+                    console.error("Missing value for --thread");
+                    process.exit(1);
+                }
+                threadId = value;
+                i += 1;
+                break;
+            }
+            case "-w":
+            case "--workdir": {
+                const value = argv[i + 1];
+                if (!value) {
+                    console.error("Missing value for --workdir");
+                    process.exit(1);
+                }
+                workdir = value;
+                i += 1;
+                break;
+            }
+            case "--json":
+                json = true;
+                break;
+            case "-h":
+            case "--help":
+                printUsage();
+                process.exit(0);
+            default:
+                promptParts.push(arg);
+        }
+    }
+    const prompt = promptParts.join(" ").trim();
+    return { prompt, promptFile, threadId, workdir, stream, logFile, json };
+}
+async function main() {
+    const { prompt, promptFile, threadId, workdir, stream, logFile, json } = parseArgs(process.argv.slice(2));
+    const promptText = promptFile != null
+        ? fs.readFileSync(promptFile, "utf8")
+        : prompt;
+    if (!promptText.trim()) {
+        console.error("Prompt is required (inline or via --prompt-file).");
+        printUsage();
+        process.exit(1);
+    }
+    const apiKey = process.env.CODEX_API_KEY;
+    const threadOptions = {
+        workingDirectory: workdir ?? process.cwd(),
+        approvalPolicy: "never",
+        sandboxMode: "danger-full-access",
+        skipGitRepoCheck: true,
+    };
+    const codex = apiKey ? new Codex({ apiKey }) : new Codex();
+    const thread = threadId
+        ? codex.resumeThread(threadId, threadOptions)
+        : codex.startThread(threadOptions);
+    if (stream) {
+        const streamed = await thread.runStreamed(promptText);
+        let lastAgent = "";
+        let usage = null;
+        const items = [];
+        for await (const event of streamed.events) {
+            // Log event summaries to stderr
+            if ("type" in event) {
+                if (event.type === "item.completed" && "item" in event && event.item?.type === "agent_message") {
+                    const text = event.item.text ?? "";
+                    lastAgent = text || lastAgent;
+                    console.error(`[agent] ${text}`);
+                }
+                else if (event.type === "item.completed" && "item" in event) {
+                    console.error(`[item.completed] ${event.item.type ?? "unknown"}`);
+                }
+                else if (event.type === "turn.completed") {
+                    usage = event.usage ?? usage;
+                    console.error(`[turn.completed] usage recorded`);
+                }
+                else {
+                    console.error(`[${event.type}]`);
+                }
+                // Collect items if present
+                if (event.item) {
+                    items.push(event.item);
+                }
+            }
+        }
+        const result = {
+            threadId: thread.id,
+            finalResponse: lastAgent,
+            items,
+            usage,
+        };
+        const jsonOut = JSON.stringify(result, null, 2);
+        if (logFile) {
+            fs.writeFileSync(logFile, jsonOut, "utf8");
+        }
+        if (json) {
+            console.log(jsonOut);
+        }
+        else {
+            console.log(lastAgent);
+            if (thread.id) {
+                console.error(`thread: ${thread.id}`);
+            }
+        }
+        return;
+    }
+    const turn = await thread.run(promptText);
+    const currentThreadId = thread.id;
+    const output = {
+        threadId: currentThreadId,
+        finalResponse: turn.finalResponse,
+        items: turn.items,
+        usage: turn.usage,
+    };
+    if (logFile) {
+        fs.writeFileSync(logFile, JSON.stringify(output, null, 2), "utf8");
+    }
+    if (json) {
+        console.log(JSON.stringify(output, null, 2));
+    }
+    else {
+        console.log(turn.finalResponse);
+        if (currentThreadId) {
+            console.error(`thread: ${currentThreadId}`);
+        }
+    }
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Codex run failed: ${message}`);
+    process.exit(1);
+});