Claude Code OS
An AI OS is a folder of plain markdown files holding your business, your voice and how you work. Write it once and you stop re-explaining yourself every session.Claude Code reads it at the start of every session, wherever you run it.
What is Claude Code?
Claude Code is Anthropic's agentic coding tool. It reads your project, edits files and runs commands, and it works through a whole task rather than answering one question at a time.
It is not 1 app. The same engine runs in a terminal, in the Claude Code desktop app, inside VS Code, JetBrains and Cursor, in your browser and in the Claude app on your phone.
It needs a paid plan: Pro, Max, Team, Enterprise or Console. The free Claude.ai plan does not include it.
What is Claude Code OS?
Claude Code OS is a folder of plain markdown files that Claude Code reads before it does anything else. Your business in one file, how you write in another, what you sell in a third.
It is not a plugin and there is nothing to install. It is plain text files, in a shape Claude Code already looks for.
Where they sit is up to you. In the project you are working in, in a folder above it, in a repository a cloud session checks out, or on a machine you connect to.
The name for the shape is an AI OS. The same folder works in Codex, Cursor and Gemini CLI, because AGENTS.md and GEMINI.md are symlinks to the same rules file.
Why does Claude Code need one?
Every Claude Code session begins with a fresh context window. So it knows your codebase and nothing about you.
That is why you keep re-explaining what you sell, who you sell to and how you write. Not because it forgot. Because it was never told.
And Claude Code is already reading files at launch, whether you wrote them or not. It loads CLAUDE.md from your working directory and every directory above it, from the filesystem root down, before your first message.
For example, start it in ~/work/acme/api and it reads ~/work/CLAUDE.md, then ~/work/acme/CLAUDE.md, then the one in api. Instructions closest to where you launched are read last, so the most specific wins.
An AI OS is what you put in that chain.
What goes in it
Anything you would otherwise type again next session.
Anthropic's own guidance is to add to CLAUDE.md when Claude makes the same mistake twice, when a review catches something it should have known, or when you type the same correction you typed last week.
Anthropic's guidance is to target under 200 lines per file. That is a target, not a cutoff: a longer file still loads, it just consumes more context and Claude follows it less reliably.
The real cutoff is 4 MiB, and past that the file is skipped entirely.
Claude Code also writes back
Auto memory is on by default, and it is a separate thing from your files. Claude saves its own notes about your preferences, your corrections, and project context it cannot read off the code.
Those live in ~/.claude/projects/<project>/memory/, with a MEMORY.md index. The first 200 lines of that index, or the first 25KB, load at the start of every conversation.
So your AI OS is what you tell it, and auto memory is what it worked out. Both load on launch.
The Claude Code OS path
6 steps, 39 lessons, about 6.3 hours end to end. You do not have to do it in order, but it is written so each step leaves you somewhere useful.
7 are written so far. The rest are marked as coming rather than linked, because a link to a page nobody wrote wastes your click.
BeginnerIntermediateAdvanced
Step 1: Decide if this is for you
Beginner, 24 min
- 1.1What is Claude Code?8 min
- 1.2The 5 Claude surfaces6 min
- 1.3Which model should you use?5 min
- 1.4Pricing and plans5 min
You know what Claude Code is and what it costs.
Step 2: Get it running
Beginner to Intermediate, 49 min
The desktop app needs no terminal and takes about 5 minutes. If that is all you want, do 2.1 and skip to step 3.
- 2.1Install Claude Code12 min
- 2.2The Claude Code interface8 min
- 2.3Claude Code in VS Code10 min
- 2.4Claude Code in Antigravity8 min
- 2.5Permission modes7 min
- 2.6Keyboard shortcuts4 min
It runs, and you know what it is allowed to touch.
Step 3: Give it your AI OS
Beginner to Intermediate, 63 min
This is the step the other 5 exist for.
- 3.1Set up a Claude Code workspace20 min
- 3.2CLAUDE.md, the soul of Claude Code15 min
- 3.3The .claude folder explained10 min
- 3.4Git and GitHub for your AI OS10 min
- 3.5Connect Claude Code to your AI OS8 min
Every session starts already knowing your business.
Step 4: Operate it day to day
Beginner to Intermediate, 79 min
Reference rather than a sitting. Come back to these.
- 4.1Claude Code commands10 min
- 4.2Secret Claude Code commands8 min
- 4.3How to prompt Claude Code10 min
- 4.4Plan mode8 min
- 4.5Stop Claude Code burning your tokens12 min
- 4.6Undo: checkpoints and rewind6 min
- 4.7Voice dictation5 min
- 4.8Debugging and troubleshooting8 min
- 4.9Best practices12 min
It stops going wrong, and you know why when it does.
Step 5: Extend it
Beginner to Advanced, 75 min
Nobody reads this in order. Each page is entered from a problem.
- 5.1Connectors: the 23 I built15 min
- 5.2Claude Code skills12 min
- 5.3MCP servers12 min
- 5.4Official plugins8 min
- 5.5Subagents10 min
- 5.6Hooks10 min
- 5.7Agent teams8 min
It reaches the tools you already use.
Step 6: Run it without you
Beginner to Advanced, 86 min
- 6.1Work while you are away10 min
- 6.2Routines10 min
- 6.3Scheduled tasks8 min
- 6.4Dispatch8 min
- 6.5Remote Control10 min
- 6.6Channels: Telegram, iMessage, Discord15 min
- 6.7Build a custom channel15 min
- 6.8Parallel work10 min
You message it from your phone and it works on your machine.
Best practices
Work down this list once and you are done.
- Put a CLAUDE.md at the root of the project you work in most
- Keep it under 200 lines, and split anything longer into
.claude/rules/ - Write instructions specific enough to verify: "use 2-space indentation", not "format code properly"
- Run
/contextand check your files appear under Memory files - Add to it the second time you correct Claude on the same thing
- Symlink AGENTS.md to it so Codex, Cursor and Gemini CLI read the same rules
Claude Code FAQs
Have questions about running an AI OS in Claude Code? Find answers to the most common ones below.
A folder of plain markdown files holding your business, your voice and how you work, in a shape every AI agent reads at the start of a session.
It is plain text files. There is nothing to install and no service to sign up for, though you do need Claude Code itself.
It loads `CLAUDE.md` from your working directory and every directory above it, from the filesystem root down.
Files in subdirectories below you load later, when Claude actually reads something in them.
The one closest to where you launched. Everything found is concatenated in order, root first, so the most specific instruction is read last.
Within a directory, `CLAUDE.local.md` is appended after `CLAUDE.md`, so your personal notes are the final word at that level.
Run `/context` and look under Memory files.
If a file is not in that list, Claude cannot see it, and no amount of rewriting it will help. `/context` is one of the 16 worth knowing.
Target under 200 lines. That is guidance, not a limit: a longer file still loads, it just eats context and Claude follows it less reliably.
The hard cutoff is 4 MiB, and a file over that is skipped entirely. If yours is growing, move the parts that only matter sometimes into `.claude/rules/`, which load only when Claude touches matching files.
Yes. Claude Code reads `CLAUDE.md`, and the other agents read `AGENTS.md` or `GEMINI.md`.
Make those symlinks to the same file and every agent reads identical rules. That is what stops an AI OS becoming 3 slowly diverging copies. Each agent has its own page: Codex, Cursor, Gemini CLI.
You write CLAUDE.md. Claude writes auto memory.
Yours holds instructions and rules. Its own holds what it learned from correcting course with you, and it skips anything it could work out from the code itself. It lives in `~/.claude/projects/<project>/memory/` as plain markdown you can read, edit or delete.
Because a mid-session edit does not apply. Your project-root and user-level CLAUDE.md are read at launch, and changing the file during a session does not retroactively change what Claude is working from.
Run `/clear`, run `/compact`, or restart. Then it reads the new version. Both are in the command list.
Yes. Open `/memory` and use the toggle, or set `autoMemoryEnabled` to false in a project's settings.
There is also `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` if you would rather do it with an environment variable.
The project root `CLAUDE.md` does. After compaction Claude re-reads it from disk and puts it back.
Instructions you only said in conversation do not survive. That is the argument for writing them down rather than repeating them.
Yes, and there are 2 different answers depending on how you got there. A cloud session runs on Anthropic's infrastructure and checks out your repository, so your AI OS has to be committed to it.
Remote Control is the other way. It connects the web or the phone app to a session running on your own machine, so the folder never moves and nothing needs committing. Your phone is the screen, not the computer.
Worth knowing: your files and commands stay on your machine, but the transcript is held on Anthropic's servers while the session is connected.
On the local surfaces, the CLI, Desktop, VS Code and JetBrains, configuration and project memory are shared, so all 4 read the same files.
Check `/context` first, because the usual answer is that the file never loaded.
After that it is usually vagueness or a contradiction: 2 files saying different things, and Claude picking one. CLAUDE.md is context, not enforcement, so anything that genuinely must happen every time belongs in a hook instead.