-
-
Four constraints fixed before any code was written, and the seven layers they hold up.
-
Nine claims the project made about itself that were not true — and were fixed.
-
Intent OS — a flight recorder for AI agents
-
What `intent-os inspect latest` prints: every step, every model call, the cost, and the exact step that failed.
Inspiration
I use coding agents constantly, and the thing that frustrated me was never that they failed — it was that when they failed, I could not find out why.
You give an agent a task. It thinks for several minutes. It reads files, calls a model, edits code, runs your test suite. Then it reports one line: "Done." Or worse, it fails and tells you nothing about where.
I didn't want a better agent. I wanted to be able to see.
The options today are all bad. Read its chat log — that's a narrative, not a record; it tells you what the agent said it did. Adopt a hosted observability SaaS — that needs SDK instrumentation inside code you control, and ships your traces to someone else's cloud. Or guess.
None of those work on the agents that matter most, because Claude Code, Codex and Cursor are closed products. You cannot add an SDK to them. You can only watch them from the outside. That gap is Intent OS.
What it does
Intent OS is an open-source flight recorder for AI agents. It records execution from the outside, at the network boundary — no SDK integration, no framework assumptions, no code changes, and no cooperation required from the agent being observed.
Three commands carry it:
| Command | Question it answers |
|---|---|
intent-os proxy start |
Record everything. Sits between the agent and the model API. |
intent-os inspect latest |
What happened? Rebuilds the timeline: goal, steps, model calls, tokens, cost, and the exact step that failed. |
intent-os doctor |
What went wrong, and how do I fix it? |
The trace it produces:
[!!] Goal: refactor-auth-to-jwt
Runtime: anthropic (AnthropicAdapter)
Duration: 14327ms
Cost: $0.0842
Tokens: 4891
Error: test_jwt_verify failed
-- Timeline (6 events) --
[10:05:39] > START (runtime) refactor-auth-to-jwt task=plan
[10:05:40] > INVOKE (adapter) read-files task=read-files
[10:05:44] OK DONE (runtime) read-files task=read-files
[10:05:47] > INVOKE (adapter) modify-auth task=modify-auth
[10:05:53] OK DONE (runtime) modify-auth task=modify-auth
[10:05:54] !! FAIL (runtime) run-tests task=run-tests
It runs entirely offline. intent-os demo --auto produces that trace with no API key and no network.
How I built it
I started with constraints rather than code. Four rules, fixed before anything else, that every later design had to satisfy:
- R1 — the Control Plane owns no state.
- R2 — no direct inter-processor communication (everything routes through the Scheduler).
- R3 — the Event Bus is the single source of truth. All state changes are events.
- R4 — capabilities are stateless.
They exist to make "what did the agent do?" answerable by construction rather than by careful logging. R3 is the reason the flight recorder works at all: there is no second source of truth for it to drift from.
I also fixed a hard product boundary before writing code: Intent OS does not standardize intelligence, it standardizes interaction. It deliberately does not specify which model to use, how to write prompts, or how to reason. Without that line the project drifts into being yet another agent framework.
Then ten specification documents, then the implementation. It's Python — 47,663 lines, of which 16,465 are tests. The test suite runs in CI on every push across Python 3.10, 3.11 and 3.12.
On how it was written: the implementation was AI-assisted throughout (Claude Code), so the code volume is largely machine-generated. What I contributed is the part an AI cannot originate on its own behalf — the architectural constraints, the specifications, the scope decisions, and the verification discipline. I'd rather say that plainly than let a judge discover it in the git history.
Challenges I ran into
Building this submission meant checking whether the project's claims about itself were true. Nine of them were not, and that became the most interesting part of the work.
The test suite had never run. CI failed on every run, because the install step ran pip install .[all] from the repository root — where there is no pyproject.toml, since it lives in reference-runtime/. The tests had never executed. The "tests passing" badge in my README was a static image encoding a number nobody had ever verified. Behind that: pytest was in no dependency extra, and all = ["ask", ...] referenced a sibling extra by name — which PEP 621 does not support — so pip resolved it to an unrelated PyPI package called ask and installed a stranger's code.
The flight recorder did not record. The proxy opened its own events.db while every reading command opened the shared intent.db, so captured agent traffic went somewhere nothing looked. Once both sides shared one database, inspect still found nothing, because it listed traces from execution_records and proxy traffic is recorded as events. Fixing that surfaced a third: the renderer read cost, tokens and error outside the branch that assigns them — and a trace without an execution record is exactly that case.
It only worked on my machine. Once CI could finally run, 18 tests failed on Linux. parse_manifest accepted either a file path or raw YAML and told them apart with Path(source).exists() — which on POSIX raises OSError(ENAMETOOLONG) for any string longer than a filename. A manifest is always longer than a filename. Windows returns False instead of raising, so it had been invisible on the only machine it had ever been run on.
Two claims were simply overstated. I had written "ten frozen specifications"; six of the ten are marked Frozen and three are still design drafts. And COMMERCIAL.md sold a governance/audit/SSO tier as commercial-only when nothing in the codebase is gated at all — those commands run in the free build, and SSO does not exist. I corrected both, in the submission and in the repository.
I think the honest summary is this: every component worked, and the connections between them did not. A flight recorder whose own test suite reported success from a job that never executed, and whose own capture path wrote to a database nothing read, is a specific and interesting kind of failure — and it is exactly the failure mode this product exists to make visible.
Accomplishments that I'm proud of
- 919 tests passing, green on CI across three Python versions — for the first time in the project's history.
- It genuinely works end to end. I verified three separate paths from a clean install before submitting: demo → inspect, a real local language-model run through Ollama, and the proxy capturing live API traffic.
- I found and fixed a real security issue in my own project.
docs/CNAMEdeclared a domain I do not own as the GitHub Pages custom domain — meaning whoever registered that name could have served a site under this project's identity. It's removed. - A working product, not a mockup. It installs. It's on PyPI. It has real specifications and a documented API.
I'll be honest about the other side too: 2 GitHub stars, no external users yet, and I am not yet a daily user of my own tool. That's the gap I'm working on next.
What I learned
The missing piece is usually the layer nobody is building, not the model everyone is racing on. That instinct is what drew me to this problem, and it is the same instinct that draws me to quantitative finance.
Verification is a discipline, not a step. The bugs above were not hard to fix — most were a few lines. They were hard to notice, because the project was busy reporting success. I now distrust any claim in my own work that I have not personally watched happen, and I've started writing the command that proves each claim into the documents themselves.
Constraints pay for themselves. Fixing R1–R4 before writing code is why a record of execution was reconstructible at all. Removing that second source of truth is what made the timeline trustworthy.
What's next for Intent OS — Flight Recorder for AI Agents
Next: be user #1. Run intent-os proxy start continuously for a week and fix whatever breaks. The tool has never been used by anyone for a sustained period, and that's the highest-value next step — it doesn't need anyone's permission.
Then: first external user. The launch drafts are written; feedback from a real user becomes the next set of features.
Longer term: make the governance layer real enough to pay for. That's the business model. Right now it's an intention, not a product, and I've labelled it that way rather than presenting a pricing table as though someone could buy it today.
Try it in 30 seconds, no API key required:
pip install "git+https://github.com/haihaoxu/intentos#subdirectory=reference-runtime"
intent-os demo --auto
intent-os inspect latest
Install from the repository, not from PyPI — the published 0.15.2 predates the fixes above.
