The Agent OS Stack.
A picture of every layer in the system. You at the top, the secrets vault at the bottom, the agent in the middle wiring them together. Keep this card open when something breaks so you can point at the layer that owns the failure instead of guessing.
- A mental model of the whole OS from the keyboard down to where credentials live. Every layer named, in order, top to bottom.
- A debugging starting point when something stops working. The stack tells you which layer to check first instead of poking at random.
- A shared vocabulary for the other cards. Every build card in the library plugs into one of these layers. This is the map.
How this fits in the OS.
Nothing. This card is the picture of the system. Read it before you build any one layer, or when something breaks and you need to find which layer owns the failure.
Every other card in the library plugs into one of the layers below. Treat this as the index. Each layer links to the card that builds it out.
A shared vocabulary for everything else. Once you can name the layer, you can name the failure, the dependency, and the next move.
The shape.
The agent OS is a stack. You are at the top. Your secrets are at the bottom. The agent in the middle is what wires the two together. Each layer talks to the one above and the one below it. When a workflow breaks, the failure lives in exactly one layer, and the picture below tells you which one to open first.
Follow one request through the stack.
The layers are easier to feel when you watch a single request move through all of them. It is 7 a.m. A scheduled task fires your /morning command. Here is the whole trip, top to bottom:
- The schedule fires the command on a timer. You are still asleep.
- The command wakes up and reads your CLAUDE.md to learn your priorities, your projects, and the voice the brief should be written in.
- Claude Code takes that and reaches out through the connectors: Gmail for what landed overnight, Calendar for today.
- Secrets quietly hand the agent the API key for each of those calls. No key ever appears in the open.
- The agent checks the vault for context the inbox does not have, like the client note you flagged yesterday.
- The command composes a three-line brief in your voice and writes it where you will see it first.
- RESULT: a brief waiting before you open your eyes. Every layer touched, in order. That is the stack working.
Layer by layer.
Every layer, top to bottom, with what it does and the card that builds it out. The order is the stack itself, no numbering to memorize.
| Name | What it does | Build card |
|---|---|---|
| You | The director. Decides what's worth automating, judges the output, owns the work that's left when the system handles the rest. | None. This is the seat you sit in. |
The brain fileCLAUDE.md |
The persistent context file the agent reads before every session. Who you are, how you work, what's on your plate, how you want to be talked to. The quality of every downstream layer is bounded by what's in here. | Your Brain File |
| The agent Claude Code CLI |
The agent that runs in your terminal. Reads your brain file, calls the connectors, edits files, runs commands, drives the scheduled tasks. Everything else in this table is something this layer reaches out to. | What Is Claude Code |
| The connectors MCP servers |
The doors out of the room. MCP servers (Claude Desktop calls these connectors) wire the agent to Gmail, Calendar, Notion, Slack, and anything else with an API. Each connector adds one tool the agent can reach. For services with their own pre-built command-line tools, a borrowed CLI replaces the connector with something more controllable. | MCP Servers · Borrow a Working CLI |
| The vault Obsidian on disk |
Your knowledge base. Plain markdown files in a folder the agent can read and write. Notes you take, transcripts, briefings, anything you want the agent to remember across sessions. The agent's long-term memory lives here, not in the chat window. | Cairns Three Tiers |
| The named workflows Custom commands |
A multi-step workflow you've named so you can invoke it with one word. /morning pulls your calendar plus inbox and gives you the top three. /triage sorts new mail into folders. Every command is a workflow that uses the layers above it: reads the brain file, calls connectors, writes to the vault. |
Slash Commands and Skills |
| The schedule Scheduled tasks |
Workflows that fire on a clock instead of on a keypress. The morning brief that lands in your inbox at 7 a.m. The weekly digest that drops Friday. The overnight sweep that triages your inbox before you wake up. The same named workflows as the custom commands above, just triggered by a timer. | Heartbeats and Crons |
| The vault under the vault Secrets |
Below everything else: where the real credentials live. Infisical is the durable setup the workshop installer signs you into, with 1Password as an alternative and a gitignored .env or .env.local as a workshop bridge. The agent reads keys from this layer at runtime. No real key ever lives in the chat, in your brain file, or in the repo. If this layer leaks, everything above it is compromised. Treat it accordingly. |
Secrets Management and Wire Your Secrets Manager. |
What each layer looks like when it breaks.
The stack earns its keep when something stops working. Each layer fails in its own recognizable way. Match the symptom, open that layer first, and skip the guessing.
| Layer | What it looks like | First move |
|---|---|---|
| Brain file | The agent ignores your preferences or asks for things it should already know. | Open CLAUDE.md. Is it current, and is the agent actually loading it? |
| The agent | Nothing runs, or a command is not found. | Check Claude Code is installed and up to date. |
| Connectors | "I can't access your Gmail," or an auth error on one tool. | Reauthenticate that MCP server, or confirm the connector is still added. |
| The vault | The agent can't find your notes, or writes them to the wrong place. | Check the vault path and that the folder exists where the agent expects it. |
| Named commands | The command runs, but does the wrong steps. | Open the command definition. The workflow itself is off. |
| The schedule | The brief never showed up at all. | The timer did not fire. Check the cron or heartbeat. |
| Secrets | Auth fails across several tools at once, or "missing API key." | The key is not loading from the vault. Confirm the reference resolves at runtime. |
How to use this card.
This card teaches the picture, not how to build any one layer. Three uses:
- When you're learning. Read the stack top to bottom, then pick the layer you want to build next and open its build card. Every other card in the library is one layer deep on this map.
- When something breaks. Walk the stack. Did the agent read the brain file correctly? Is the connector still authenticated? Is the vault path right? Did the schedule fire? The failure lives in one layer. Find it, fix it, move on.
- When you're explaining what you built. The stack is the answer to "what is this thing?" You at the top, secrets at the bottom, an agent in the middle that wires the two together with named workflows and a clock. That's the whole shape.
Claude Code is one layer. A good agent OS is the whole stack. The setups that fade are the ones where someone installed the agent and stopped. The setups that compound are the ones where every layer below the agent is real: a brain file that's current, connectors that are wired in, a vault the agent actually reads, commands you actually invoke, a schedule that fires while you sleep.
Where to go next.
Pick the layer you want to build out first. Three natural starting points: