Milhouse

Milhouse

Open source on GitHub · Apache-2.0

Status: pre-alpha, in active development. The architecture and contracts are real and under formal gates; the runtime isn’t finished. Don’t point it at production data yet. Everything below distinguishes what’s built from what’s designed.

---

The Problem Nobody Fixes

Engineering teams are drowning in dashboards and starving for closed loops.

Something breaks. Someone notices. A ticket gets written, a fix gets shipped, the ticket gets closed — and nobody ever checks whether the thing that broke stopped breaking. Work is marked done because a person asserted it was done. The dashboard that would have told you otherwise is right there, and no one goes back to look.

This is an old problem, and AI-assisted development is making it dramatically worse. Agents are exceptionally good at declaring success. They will tell you the fix is in, the tests pass, the issue is resolved — and they are sincere, and sometimes they are wrong, and the loop that would catch it doesn’t exist.

---

The Idea: You Don’t Get to Mark Your Own Work Verified

Milhouse’s core move is to take that authority away from everyone, including itself.

Only the verification engine may mark a feedback item verified or regressed. There is no operator override in 1.0. You can request verification — that schedules an observation. It does not let you choose the outcome. An item becomes verified when the same class of signal that produced it is observed to have changed, and not before.

The full loop:

failure/workflow signal
  → redacted durable record
  → alert + deterministic curator rule
  → open feedback item
  → accepted, with an owner
  → shipped, with change + validation evidence
  → same-class observation by the verification engine
  → verified or regressed

Every transition is recorded with a deterministic transition ID, previous and new state, a monotonic revision, the expected revision, derived actor identity, rationale, request ID, and evidence. Writes use compare-and-swap semantics. The lifecycle is append-only — current state is a projection, never an in-place source of truth you can quietly edit.

That’s the difference between a feedback loop and a feelings loop.

---

Local-First, and Meant It

Milhouse does not require a hosted service and sends no call-home telemetry. It never stores raw prompts, responses, agent transcripts, or tool output. Signals are normalized and redacted before they are durably persisted, not after.

This isn’t a privacy checkbox. It’s the reason a team can point the thing at their real workflow at all — including the agent-session signals, which is exactly the data nobody is willing to ship to a vendor.

What it collects: health, deploy, workflow, error, and privacy-safe agent-session signals.

---

Architecture

• Segmented JSONL spool — acknowledged records land in a local, self-describing, atomically published segment log
• SQLite — transactional control state: fenced leases, a global commit barrier, a durable segment ledger, bounded readers, reconciliation, quarantine and recovery
• ClickHouse — local analytics over the collected signal
• Degrades honestly — collection continues when ClickHouse or a provider is unavailable, rather than dropping data or blocking the workflow
• Surfaces — a bounded CLI, a local MCP server (so agents can read the feedback state directly), generated reports, and a .milhouse/ brief directory that lands feedback where the team and its agents already look
• Optional and opt-in — GitHub Issues and redacted Telegram summaries, neither of which may decide verification state

---

/doh

When completed work missed intent, /doh produces a neutral postmortem.

Everything is in scope — operator input, requirements, planning, agent behavior, implementation, validation, documentation, workflow. Notably, the human’s instructions are in scope too, not just the agent’s output. Evidence is bounded and treated as untrusted data, and personal or profanity heuristics are prohibited by design. The goal is a postmortem you can actually read the day after, without it having picked a villain.

---

Building It in the Open

The work is gated. Milhouse follows work packages W00–W18 against an authoritative implementation plan, and a package’s behavior is planned, not available, until its gate passes. W01 and G02 are accepted; W03 — durable storage foundations — is in progress. G03 has not passed. Replay, retention, ClickHouse, collectors, querying, and the operational runtime are not accepted yet, and the README says so in the first paragraph.

There’s a maintainer-authored engineering journal that explains each merged milestone in plain language and links the exact evidence, explicitly separating implemented behavior from planned work.

Building a verification tool that lets people mark their own work complete would have been a bad joke. So the project holds itself to the same rule it sells.

---

Milhouse is the productized version of a problem I kept hitting while running agentic development in production: the loop between shipping and knowing was always the part held together by memory and good intentions.