Week of June 28 — IkeOS Goes Public, Grows a Spine, and Learns to Watch Itself

This was the kind of week where the volume of what shipped almost obscures how coherent it all was. Every session this week pulled in the same direction: making IkeOS a platform that is honest about its own design, observable from the inside, and safe to share with the world.

That framing — safe to share — turns out to be harder than it sounds.

v0.1.0 Ships

On Tuesday, IkeOS shipped its first public release. theryancoleman/ikeos is live on GitHub with 333 passing tests, clean public-ready docs, and a GitHub release marking the milestone.

Project ‘Imi has been building toward this since it started. The release marks a real transition: from a personal homelab tool to something replicable. But shipping it surfaced a design gap that had been easy to ignore while everything lived in private repos.

IkeOS can trigger AI sessions. It cannot choose which model runs in them. A hardcoded --model sonnet buried in tmux.py means you can’t spawn a different model session from the UI. That gap is now a vault entry and the motivation for the model selection work on the roadmap. The release was right to ship — the gap was right to name.

The Driver Architecture Gets a Real Spine

Before this week, IkeOS’s relationship with the Claude Code session manager was spread across four separate code paths, each with its own HTTP boilerplate and slightly different error handling. That kind of duplication is fine when a system is small and moving fast. It becomes a maintenance tax when the system is being prepared for contributors.

The week’s most substantial engineering work was the driver consolidation: a systematic architectural refactoring that landed across a coordinated series of sessions.

What shipped:

• session_client.py — a typed SessionResult dataclass and create_session() function that centralizes all four POST /sessions call sites. One file owns the wire contract; everything else calls it.
• driver.py — an intent layer that owns every slash-command string sent to Claude. Moving prompt construction out of scattered call sites and into a single place is what makes the driver replaceable without rewriting the platform.
• platform.py — configuration helpers that de-hardcode the project slug and version path. Zero hardcoded strings remain in the app layer.
• routes/auth.py — a require_capture_token decorator, correctly placed at the routes layer (not in services, which must be pure Python), importable across all route modules.

The consolidation also produced something more important than the code: a documented HTTP contract. docs/SESSION_DRIVER_API.md captures the session manager wire API at v0. The public/private boundary is now explicit. Someone who wants to build a different driver — different AI engine, different orchestration model — has a spec to implement against, not a pile of Flask source to reverse-engineer.

The Adapter Layer Goes Public

In parallel with driver consolidation, a second architectural decision shipped: the IkeOS Claude Code skills move into the public repo.

The five core skills (/housekeeping, /triage, /close-session, /schema-check, /promote), the stophook, and the session-manager reference implementation were all extracted from the private claude-config repo and landed in adapters/claude-code/ in the public ikeos repo. Everything is parameterized by five environment variables. The README and .env.example are in place.

This completes the critical public-release gate. Before this session, someone cloning the repo could read about a driver architecture but couldn’t run one. Now they can clone, fill in five env vars, and have a working setup. The platform/adapter boundary is explicit for the first time.

One unexpected find during the move: rotating the CAPTURE_TOKEN (a security prerequisite for publishing) surfaced a live token on disk, plus two more embedded in accumulated permission rules. Publishing is 80% secrets hygiene.

Security: Closing the Gaps

A dedicated security pass closed several issues that had accumulated during the feature-shipping sprint:

• Open redirect in a route that forwarded user-controlled URLs without validation — fixed with an allowlist.
• Path traversal in file-serving endpoints — fixed with boundary validation.
• Stale cache returning outdated data after writes — fixed with explicit invalidation.
• XSS in the metrics view — fixed with output escaping.
• JS filename injection via unescaped user-controlled values in a script tag — fixed.
• Auth gate on run_task — the endpoint that triggers housekeeping runs was missing the capture token check. Fixed.
• Bare except clauses logging nothing useful — replaced with exc_info=True so stack traces actually appear.

None of these were individually catastrophic, but before open-sourcing a project, the bar for “acceptable gaps” drops. This pass cleaned the slate.

The Platform Learns to Watch Itself

On Friday, something qualitatively different shipped: the Reflection Health widget.

IkeOS had, for weeks, been running a reflection system — accumulating weak signals, tracking acceptance rates, noting abrupt session endings. The data lived in flat files (library/weak-signals.json, library/metrics.json) that were invisible from the platform. You had to hunt for them in a text editor to know if signals were stacking up.

The widget surfaces this on the dashboard: active weak signals, pending promotions, acceptance rate, abrupt endings. The platform can now see its own health at a glance.

Alongside it, the housekeeping run ledger shipped: every scheduled housekeeping run now emits stats to the metrics event stream, and the housekeeping page shows the last 10 runs with timing and outcome. “What happened while I was away?” now has an answer you can read without digging through logs.

One bug found during this work is worth flagging: Jinja2 templates don’t support Python’s .get() method — they use the | default() filter syntax. The implementer wrote .get(), which would have silently crashed at render time in production. Caught by the code review stage before it reached main. The reason it was caught: the review pipeline runs against a rebuilt Docker image, not stale baked-in code. Always rebuild before you test.

The AIOS Engineering Standard

Late in the week, a different kind of artifact shipped: docs/engineering/CLEAN_CODE_FOR_AIOS.md — a 14-section engineering guide for human-AI collaborative development, paired with a /code-review skill that evaluates any codebase against it.

The gap it fills is real. IkeOS had accumulated per-project rules files that shaped how Claude wrote code for this specific context. But nothing traveled across all projects, and nothing was enforceable by a reviewable skill. The standard addresses territory that Clean Code (2008) never touched: prompt quality, agent responsibility boundaries, context management, capability safety gates, and the fire-and-forget pattern for cross-service calls.

The /code-review skill makes it executable rather than aspirational.

What’s Next

The roadmap is coming into focus around two themes.

Model selection is the most concrete gap: the session manager needs a model parameter so the platform can choose which AI engine runs a session from the UI. This is the prerequisite for spawning Opus sessions for architecture reviews, Haiku for fast triage, and anything else as the model landscape evolves.

Portfolio observability is the longer arc. The platform now has enough infrastructure — metrics events, capability gates, session ledger, reflection health — to start monitoring the project portfolio as a whole, not just IkeOS itself. That work is planned and partially specced. It runs itself via a monthly remote routine that files checkpoint issues comparing reality against the plan.

The system is starting to run its own maintenance. The platform can watch itself. The adapter contract is public. The security baseline is clean.

That’s a good week.