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.
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, eval-drift, watchdog) and every scheduled task and timer.
03Skills, 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.
04Memory & 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.
05Data 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.