🧠 CAIOS — Claude AI Operating System

Turn Claude from a chat window into an operating system that remembers, learns, and executes.

CAIOS is a personal AI operating system built on top of Claude, Obsidian, and the Model Context Protocol (MCP). It gives Claude a persistent memory, a control dashboard, a real approval-gated publishing pipeline, a notification system that reaches your phone, and an optional multi-agent "Brain" that can delegate work to other AI coding tools. It was built and battle-tested over 22 real sessions — not a scaffold, a running system.

📖 Built and maintained by Abanob Sheref. Contributions, forks, and modified copies are welcome — see Contributing below.

Why this exists

Every fresh Claude conversation starts from zero. CAIOS solves that with three ideas:

Persistent memory that stays small. A tiered memory system (memory/context.md → vault/) keeps only what Claude needs to read every session small, while everything else lives one lookup away. A token budget dashboard measures this instead of guessing at it.
A real approval gate, not a prompt. Nothing gets published to social media, and no notification goes out, without either explicit chat approval or a recorded approved action in the dashboard. This isn't a system-prompt suggestion — it's enforced in code, with a JSON file as the single source of truth.
Detection by capability, not by assumption. Instead of guessing "am I in Claude Code or Cowork," CAIOS asks "can I actually reach my other AI workers right now?" and answers with a real call, not an environment variable. The same principle runs through the whole system: the prompt is a suggestion, the call is the verdict.

What it actually does

Capability	How
🧠 Persistent memory	Obsidian vault + tiered `memory/` files, with automated compression and archival that's measured, not guessed
🏗️ Control dashboard	Local web dashboard (`localhost:4590`) — light/dark theme, Arabic/English, live status of every MCP server, connector, and scheduled task
🔔 Notifications	Dual-channel: a dashboard record (source of truth) + a real Slack DM (delivery channel) — verified against a live Slack send, not just a handshake
📣 Gated publishing	Draft → shown in full (text, platform, char count, media) → explicit approval → then publish. Two approval paths: chat or dashboard
👥 Multi-agent "Brain"	Optional delegation to other AI coding tools (Cursor, Codex, or any tool you register) with explicit path ownership and a QA gate
📺 Research tools	YouTube transcript analysis, web search (Brave/DuckDuckGo), and full research report generation
🗂️ Project system	Each new effort gets its own memory-linked project folder instead of polluting the global context
⏰ Scheduled automation	Real recurring tasks (not cron-in-a-doc) that run connector health checks and report back over Slack

Architecture at a glance

CAIOS
├── memory/            ← small, always-loaded state (context, preferences)
├── vault/              ← Obsidian knowledge base (notes, research, sessions, automation records)
├── brain/               ← optional multi-agent delegation layer (identity files, task ownership, QA gate)
├── mcp-servers/    ← MCP servers Claude talks to (obsidian, youtube, search, research, social, dashboard)
├── bin/                    ← the dashboard, token budget engine, notifications, scheduled-task bridge
└── config/             ← Claude Desktop config templates, environment variables

Full design rationale, the decisions that shaped it, and the failure modes it was built to avoid: see ARCHITECTURE.md.

Quickstart

git clone https://github.com/abanobsheref216-dot/caios.git
cd caios
npm install
npm run mode              # are your other AI tools reachable? solo/team/blocked
npm run dashboard:control  # open http://localhost:4590

Then point Claude Desktop's config at the MCP servers in config/claude_desktop_config.json.example, and copy memory/context.md.example → memory/context.md.

For the full manual setup walkthrough (MCP servers, environment variables, Claude Desktop config, testing), see SETUP.md.

Verify it for yourself

npm test               # unit tests across every module
npm run integration     # real MCP handshakes — not mocked
npm run qa              # structured bug hunt, reports findings instead of hiding them

CAIOS treats a skipped test as a finding, not a pass — npm run integration counts and prints every skip at the end, because a green screen with zero real API calls is exactly the silent failure this project was built to avoid.

Contributing

Want to fix something, extend a connector, or run your own modified copy? See CONTRIBUTING.md — the short version: fork it, make your change, open a pull request. Bug reports and feature requests are just as welcome as code — see the issue templates in .github/ISSUE_TEMPLATE/.

This project has a Code of Conduct. By participating, you're expected to uphold it.

Found a security issue instead? See SECURITY.md — please don't open a public issue for it.

Installer

Want to hand CAIOS to someone non-technical? installer/ has a PowerShell installer + an Inno Setup script that compiles into a single Windows .exe: it downloads the project, creates a desktop shortcut to the dashboard, and opens a step-by-step welcome page explaining what CAIOS is and how it works. A GitHub Actions workflow builds CAIOS-Setup.exe automatically and attaches it to every tagged release — check the Releases page for the latest one. See installer/README.md for details.

caios