HEADING OS documentation

HEADING OS is an operations engine for an AI executive assistant — a library of skills, always-on rules, automation scripts, and daemons that let Claude Code act as a strategic assistant across sessions. This repository is the engine: code only, no private data.

Claude Code Python 3.11+ WSL2 · Linux · macOS Apache-2.0 Engine / data separation

The guarantee: your data cannot ship with the code. The engine is a shareable, public repository; your data is a private one the engine never contains and never leaks. That separation is enforced by six mechanical layers and a security suite that runs on every commit, not left to intention.

New here? Start with Prerequisites & install to stand up a working clone, then explore the operate and reference guides below.

Guides

Prerequisites & install

System requirements, the Python toolchain (uv / venv), the full .env, Ollama + models, the Brave automation browser, git hooks, and the data overlay.

Daemons & scheduled tasks

Install and manage every long-running daemon (bridge, sync-exchange, sentinel, fireside, watchdog) and every scheduled task and timer.

Skills, MCP & plugins

The full skill catalog by category, the MCP servers (Playwright, Pencil, Google connectors) and how to register them, and the Claude Code plugins.

Memory & ODIN

How all six memory mechanisms work — auto-memory, semantic recall, the ODIN brain, the knowledge base, threads, and the maintenance passes — and how to operate ODIN.

Data overlay structure

An annotated template of the private .heading-os-data repository and the engine / data separation principle that keeps the engine code-only.

Full deployment guide

The canonical end-to-end install walkthrough, plus the one-page Quickstart.

The mental model

HEADING OS splits one operator workspace into two git repositories:

Layer	Holds	Visibility
Engine (`.heading-os`)	Code only — skills, rules, scripts, daemons, config templates, docs.	Shareable, eventually public.
Data overlay (`.heading-os-data`)	All real data + every generated artifact — CRM, knowledge, context, threads, plans, outputs.	Private forever.

Routing between the two is declared in config/routing-map.yaml and resolved at runtime by the data-root seam in scripts/utils/workspace.py. A mechanical guard refuses to commit data-class files into the engine, so the split cannot drift. On a public clone the data overlay is simply absent and the engine runs on its defaults and *.example.* templates.

By the numbers

Every figure here is produced by CI, not asserted by hand. Counts as of v0.8.0.

554 security tests, run on every commit by the security suite over tests/security/. This is the suite that proves the guarantee above.
6 enforcement layers hold the engine and data apart: a bypass guard, a leak guard, a data-path redirect, a build partition, a runtime tree-clean check, and an unbypassable push-time wall.
Router accuracy: pending. The nightly router-accuracy trend needs a week of data before a number is published here.

Built by HEADING OS is a personal project built and maintained by Misha Hanin, and shared as an open framework. Misha is the Founder & CEO of 31 Concept (31C) and uses HEADING OS himself, but 31 Concept is not involved in it and bears no responsibility for it; any 31C-like vocabulary here is illustrative example data only. See the repository for source, license, and contribution guidelines.

Names and examples Every name, company, contact detail, figure, and scenario used as an example in this project is fictional and exists only to show how the software behaves; any resemblance to a real person or organisation is coincidental and unintended. If an example resembles you, write to misha.hanin@odinix.com with the subject HEADING OS naming and it will be changed. Full notice: DISCLAIMER.md. What changed in v0.8.0: release notes.