The Operator's Runbook · Building Your First Agentic OS · 16 Slides
Building Your First Agentic OS.
This guide walks you through how the accompanying runbook works and how to run it.
The shape · three stages, four gates
Page 02/Intro
What is an Agentic OS?
five layers do the real work; a screen is the cherry on top
An agentic OS is the system within which Claude runs. At its core is a harness, the runtime that drives the model. The harness hands Claude the right context and runs the tool calls it asks for, looping until the job is done. That loop is what turns a chat model into an agent that takes action. Claude Code is a harness.
Around that harness, the OS adds what a raw model can't hold on its own: a memory of your projects, a set of saved skills it can run on command, safety rules so it never does anything reckless, and a dashboard you actually click.
It's kind of like the operating system on your phone. iOS sits under the apps you tap, holding your photos and running everything, the home base you always come back to. This is that underneath layer, built for an AI that does real work for you.
Page 03/Intro
What you're building. Your AI.
The goal is one thing: turn a general AI into your AI. Once it's built, it remembers what you're working on. Your emails get drafted in your voice, ready for you to approve before anything sends. Repeat tasks run from a button instead of a paragraph of instructions you retype every time. Your notes stay in order, and the whole thing gets a little sharper each week.
This runbook is how you build that, one gate-checked stage at a time.
Page 04/Intro
Why a runbook. Every machine differs.
the guide can't be pasted verbatim
The build guide has seven steps, and no two computers run them the same way. The runbook is the layer that makes the guide run on your specific machine: it audits what you have, adapts the seven steps to fit, and runs them.
A gate sits between each stage. It confirms the last stage produced something valid before the next one starts. Nothing is fudged, and nothing runs by surprise.
A runbook turns a guide you read into a build you can trust on a machine you have never seen.
Page 05/Intro
Three stages. Four gates.
a gate is a script; a failing gate stops the line
Audit probes your machine and writes a report. Adapt turns that report plus the seven steps into a plan built for you. Run executes the plan in Claude Code and records what happened. Everything is read-only until Run, and Run needs your signature first.
The gates are checks. G1 the audit is valid. G2 the plan is complete and safely ordered. G3 you approved the run. G4 every step passed. Green all the way through means the system is built.
Page 06/What it does
Stage 1. Audit.
structured, machine-readable, gate-checkable
The audit reads your OS, the versions of git, node, python and claude, what already lives in ~/.claude, and which tools are missing. It is read-only and makes no network calls. API keys are reported as present or not, never as their real values.
It then computes hard_missing, the blocking prerequisites, and a single ready flag.
Gate G1 · audit-valid
- rejects malformed or incomplete reports
- rejects a raw key that leaked into the file
- rejects ready that disagrees with hard_missing
Page 07/What it does
Stage 2. Adapt.
Claude reads the audit and writes a plan built for your machine. For each of the seven steps it records a decision: do it, adapt it, or skip it, with a reason. Anything the audit flagged as missing gets an install action, scheduled before the step that needs it.
The result is plan.json. The judgment is Claude's; the completeness is the gate's.
The adaptation is human-level judgment. The gate asks one thing: did you cover everything, in a safe order?
plan.json · one row per step, decisions + install order
Gate G2 · plan-complete
- all seven steps present, none dropped
- a skip must say what it costs
- every missing tool installed before it is used
Page 08/What it does
Stage 3. Run.
approval marker → build → run ledger
Run is the only stage that changes your machine. First you approve it, and Claude records who, when, and whether the run may do anything destructive. Then Claude works each step of the plan, runs its check, and records the result in run_ledger.json.
A destructive command needs an explicit confirm. The one exception is the throwaway file the safety test deletes.
Gate G4 · post-run verify
- every done step recorded as pass, with evidence
- ready stays false if anything is still missing
- no secret leaked into the ledger
Page 09/What it does
The four gates. Each one is a script.
G1 · after audit
Audit-valid
The report parses, has every field, and its ready flag agrees with what is missing. No raw keys.
G2 · after adapt
Plan-complete
All seven steps decided, none dropped or duplicated, and every missing tool installed before it is needed.
G3 · before run
Pre-run consent
A signed approval exists. Destructive commands need a confirm and a matching scope. No secrets in the plan.
G4 · after run
Post-run verify
Every executed step passed with evidence. The system is ready only when nothing is left unresolved.
run each from the terminal · it prints PASS, or the exact problem to fix
Page 10/What it does
Nothing runs without a signature.
the guardrails, in three lines
The runbook stays read-only until you approve. Any command that deletes, overwrites, or sends must be marked confirm, and the approval must cover destructive actions or the run is blocked.
Real API keys and passwords live in a local .env. If one appears in a plan, a ledger, or the chat, the gate fails on the spot.
The gate does not trust intent. It reads the file, and either it is safe or it is not.
Page 11/Run it
Before you start.
The runbook is a small folder that ships with this guide: an audit script, the four gates, and a couple of templates. Claude reads them, you don't. It is stdlib-only Python, so it runs anywhere Python does.
Open Claude Code in the runbook folder
In your terminal, type cd, drag the runbook folder onto the window, press enter, then type claude.
Page 12/Run it
One prompt. That's the interaction.
In Claude Code, type
/goal Build my agentic OS from this runbook. Audit my machine, make a plan for it, and ask me before you change anything.
That is the whole interaction. Claude reads your machine, writes a plan built for it, and pauses for your OK before anything changes.
It checks a gate at every stage, so a bad step stops the line instead of half-building your setup. You never run a command yourself.
One goal in, a built system out. Your only other job is to approve.
Page 13/Run it
What happens after you hit go.
four moves, one yes from you
You do not run any of this. Claude audits your machine, adapts the seven build steps into a plan, and works them one at a time.
Everything up to the build is read-only. The one thing it needs from you is a yes.
Page 14/Run it
You approve. That's your part.
Claude stops and asks
Install node and build 5 skills? This changes your machine. (yes / no)
You reply
yes
Claude stops before anything that changes your machine and asks first. Say yes to go on, no to hold.
Nothing that installs, overwrites, or deletes runs without your yes. When the last gate passes, the system is built.
Page 15/Run it
What it builds. Seven steps.
Build order, not layer order. The right tag maps each step to its architectural layer; 6 and 7 are the optional top.
Done
A green G4 means the system is built.
You audited your machine, adapted the build to it, and ran it with a check at every gate. From here, add one skill or one helper at a time.