ai-os-framework

A local-first AI operating layer for people who need AI agents to stay observable, governable, and useful in real work.

Most AI agent projects can demo intelligence. Far fewer can answer the operational questions that matter:

• What changed?
• What matters now?
• What is blocked?
• Which subsystem is drifting?
• What needs a human decision?
• Can this system recover when something fails?

ai-os-framework is an open-source starter kit for building an AI operating layer: one control plane, many domain subsystems, explicit contracts, and an executive War Room.

Created by Kenny Su, Founder, Chairman & CEO of KDAN, this project comes from a private AI OS design effort across knowledge, trading, CRM, email, content, and company-state workflows.

The public repo does not contain private data or company-specific runtime logic. It exposes the reusable framework: control-plane design, subsystem contracts, War Room patterns, health checks, and portability templates.

It gives you:

• one control plane
• multiple domain subsystems
• contract-first integration
• a War Room / operator surface
• health, observability, and recovery primitives

It is designed for systems that need to be:

• modular instead of monolithic
• contract-first instead of prompt-glued
• observable instead of opaque
• portable across local hosts and server environments

This repository is especially useful for founders, operators, and technical leaders who want AI systems that remain legible under pressure, not just impressive in isolated sessions.

It does not include private user data, personal CRM data, private email data, knowledge memory contents, or company-specific digital twin logic.

Who This Is For

• Founders and CEOs building personal or company AI operating systems
• Operators who need a War Room across tools, agents, and data sources
• Technical leaders turning AI experiments into maintainable systems
• Teams that want local-first, contract-first AI infrastructure
• Builders who are tired of losing context inside closed agent sessions

Why This Repo Is Different

Most open-source AI repos stop at one of these layers:

• model access
• prompting
• agent orchestration
• workflow automation

ai-os-framework focuses on a different layer:

• control-plane design
• subsystem boundaries
• explicit contracts
• War Room visibility
• operational recovery

That makes it a better fit for real operating environments where AI has to work across multiple domains and still remain governable.

Why This Exists

Most multi-agent setups break down for the same reason:

• too many isolated tools
• too much hidden state
• too much logic trapped inside sessions
• too little operational visibility

This framework takes a different approach:

1. define one control plane
2. let domain subsystems own their runtime logic
3. require every subsystem to publish explicit contracts
4. aggregate those contracts into a War Room
5. make health, failure, and recovery visible

What You Can See In Five Minutes

After bootstrap, you can open a minimal demo and immediately inspect:

• a shared War Room snapshot
• executive priorities, risks, and actions
• subsystem status cards
• control-plane health signals

If you want to understand the framework quickly, use this flow:

1. read this README
2. open demo/index.html
3. open demo/war_room/index.html
4. inspect the contracts and templates behind the view

What You Get

• a control-plane structure
• subsystem templates
• JSON schemas for contracts
• example subsystem outputs
• a demo War Room snapshot builder
• a minimal dashboard / War Room HTML demo
• a visual demo landing page for executive-facing walkthroughs
• a bootstrap script for first-time setup

Architecture At A Glance

Core Design Principles

1. One control plane
2. Multiple domain subsystems
3. Contracts over implicit prompt coupling
4. Operator-facing War Room
5. Observability and recovery as first-class design concerns
6. Portability across host environments

Repository Layout

ai-os-framework/
├─ demo/
│  └─ war_room/
├─ docs/
├─ framework/
│  ├─ control_plane/
│  ├─ contracts/
│  ├─ adapters/      # how runtimes / tools / agents plug in
│  ├─ auditors/      # control-plane modules that audit the AI OS
│  ├─ health/
│  ├─ war_room/
│  └─ automations/
├─ templates/
├─ examples/
│  ├─ example_trading_subsystem/
│  ├─ example_knowledge_subsystem/
│  ├─ example_email_subsystem/
│  └─ example_auditor_module/
├─ scripts/
├─ Makefile
└─ .env.example

Runtime Agnostic By Design

Subsystems can be Python scripts, Node services, n8n workflows, Claude Code skills, or webhook handlers — anything that can produce a contract-compliant daily_summary.json. See framework/adapters/ for the adapter pattern and how to plug in your own runtime, data source, or agent.

Built For Self-Host First, Commercial-Ready

This framework is designed for SMB founders, operators, and individual builders who want to self-host an AI operating layer today.

The contract schemas also reserve optional fields (tenant_id, policy_id, audience, data_classification, provenance) for future multi-tenant, RBAC, and compliance layers. Self-host users can ignore them — they have no effect on single-org deployments.

Quickstart

Option A: one command

./scripts/bootstrap.sh

Option B: step by step

cp .env.example .env
python3 scripts/build_demo_war_room_snapshot.py
python3 scripts/validate_contracts.py

Note: Core setup requires only Python 3 standard library. Image generation scripts require Pillow: pip install -r requirements-images.txt

Then open:

• demo/index.html

Expected output:

• output/war_room_snapshot.json

Demo

The demo War Room shows how a control plane can consume thin subsystem contracts from:

• trading
• knowledge
• email

without being tightly coupled to subsystem internals.

Open:

• demo/index.html
• demo/war_room/index.html

Recommended flow:

1. read the root README
2. open the demo landing page
3. open the War Room demo
4. inspect the contracts and templates that produced it

Included In v1

Contracts

• daily_summary.json
• war_room_snapshot.json
• health_summary.json
• module.spec.yaml

Templates

• control-plane module template
• subsystem README template
• daily summary template
• health summary template
• War Room snapshot template

Examples

• example trading subsystem
• example knowledge subsystem
• example email subsystem
• example auditor module (provenance auditor)

Origin

This project was created by Kenny Su, Founder, Chairman & CEO of KDAN.

It comes from an internal AI OS design effort exploring how executives, operators, and technical teams can coordinate multiple AI agents without losing visibility, context, or control.

The public repo does not contain private company data, personal memory, CRM records, email content, trading logic, or digital twin internals. It only exposes the reusable framework: control-plane design, subsystem contracts, War Room patterns, and portability templates.

This is an independent open-source framework. It should not be interpreted as an official KDAN product unless explicitly stated.

Public vs Private Boundary

This repository should stay public-friendly.

Do not put the following here:

• private CRM or email data
• real memory stores or knowledge archives
• personal or company secrets
• live tokens, keys, or host-specific confidential paths
• raw personal digital twin content

Keep those in private repos and expose them only through explicit contracts.

Recommended Usage Model

Use this framework to:

• create your own control plane
• define your own modules and subsystem boundaries
• publish subsystem contracts
• aggregate them into a War Room
• add health and retry patterns
• evolve modules into subsystems over time

Docs

• docs/architecture.md
• docs/event-model.md
• docs/module-model.md
• docs/subsystem-model.md
• docs/contract-model.md
• docs/portability.md
• docs/open_source_scope_v1.md

Roadmap

• richer schemas for health and actions
• a stronger dashboard starter
• host-adapter examples for macOS and Linux
• observability starter patterns
• subsystem promotion guide

License

Apache-2.0

Contributing

See CONTRIBUTING.md for setup instructions, how to add subsystems, and PR guidelines.