Your Personal OS (Personal Monorepo)

Related guides: Git · The Terminal · Zo Computer

Preface

A chat contains temporary working context. A new chat, a different agent, or a different device does not automatically know what happened in the old one. If important context lives only inside one conversation thread, every future session starts from zero.

The Personal OS is the fix. It is one organized folder — a personal monorepo — containing the projects, files, goals, preferences, plans, and maps that help any agent collaborate with you. It is not a special application. It is a filesystem pattern: a dependable home for durable context, synced to every computer where an agent works on your behalf.

By the end of this guide you should be able to:

Explain what problems a Personal OS solves and why agents need one.
Decide what belongs inside yours (and what must stay out).
Write an AGENTS.md that teaches any agent how to navigate your system.
Sync your Personal OS across all your devices — laptop, cloud computer, anywhere — using Git and GitHub.
(Advanced) Keep secrets and heavy media usable by your agents without ever syncing or leaking them.

Basics

1. Justification: what problems does a Personal OS solve?

Wouldn’t it be nice if all your agents knew how to find everything you are working on — or have ever worked on? You could mention something casually and the agent would know what you meant. It could find the relevant project, transcript, plan, decision, or previous attempt. It could understand how you prefer to work, what you care about, and what happened last time.

Concretely, a Personal OS solves five recurring problems:

Context trapped in conversations. Work gets “stuck” in a Codex chat, a Zo conversation, or a Claude session. When the thread ends, the context is gone. A Personal OS moves important context into durable, inspectable files that any future agent can read. This also decouples your project’s memory from any one vendor, model, computer, or chat thread — if you switch tools next year, your context comes with you.

Every agent starting from zero. Without shared context, each new session re-learns who you are, what you’re building, and how you like to work. With a Personal OS, a new agent reads your map and picks up where the last one left off.

Drifting copies across devices. You have a laptop, a phone, and (in this course) a cloud computer. If each has its own slightly different pile of files, no agent can trust what it sees. Syncing one Personal OS to all your computers creates a single evolving source of context instead of drifting copies.

No home for new work. When an agent produces something useful — a plan, a script, a report — where does it go? Without a designated home, artifacts scatter across Downloads folders and chat histories. The Personal OS is the default answer to “where should this live?”

You can’t delegate what you can’t point at. To hand an agent a real task, you need to point it at the relevant project, the relevant data, and the relevant instructions. A Personal OS makes all three pointable.

One important reframe: the Personal OS does not need to contain everything — it needs to be the dependable map to everything. Agents do not need your entire life loaded into every context window; they need a reliable index of where things are, how they connect, and how to work with them.

2. What goes inside a Personal OS

Everything! data · prompts · skills · intents · goals · problems · solutions · experiments · learnings · retros · transcripts · plans · projects · scripts · software · context — all in one place, on all your computers, available to all your agents.

In practice, the contents fall into a few categories:

Projects you want agents to work on. One folder per project, each containing its requirements, decisions, source material, development log, and outputs. When working on a particular project, open your agent in that project’s folder so it gets the right immediate context (see “Nested context” below).
Reference guides you want agents to read. Notes on how your systems work, how you like things done, guides like this one, links to documentation. Anything an agent should be able to look up instead of asking you.
Personal data you want agents to have access to. Meeting transcripts, journal entries, exported archives, research material. Only include what you’re comfortable having every agent (and every synced computer) see.
Plans you want agents to remember or follow. Goals, intents, roadmaps, project briefs, saved decisions, success criteria. When you and an agent agree on a direction, save it as a file so the next agent honors it.
Skills and prompts you want agents to use. Reusable saved prompts, skill files, and workflow instructions — the “magical upgrades” that make every future session start smarter.
Tools and scripts agents use to do their work. Small programs an agent wrote for you, automation scripts, utilities. Keeping them in the repo means every agent on every machine can run and improve them.
The map itself. An AGENTS.md at the root (next section), plus any index files that explain where things are.

What must stay out of the synced repository:

Secrets. Never commit passwords, API keys, or private credentials. The repository syncs everywhere and agents read it freely — treat anything committed as visible, forever.
Data you don’t have the right to share with a machine. Employer confidential material, other people’s private information, anything covered by a policy you’d be violating.
Heavy media. Video and audio bloat a synced repository. Commit a small index or download script instead of the bytes.

There is a subtlety here: some of these things you do want inside your Personal OS at the same time. You want your agent to have access to your API keys — without sharing or leaking them. You want your media organized alongside your projects — without dragging gigabytes through every sync. The resolution is that “in the folder” and “in the synced repository” are not the same thing: .gitignore lets a file live in your Personal OS on one machine while remaining invisible to Git and to every other computer. Section 5 in Advanced is a small guide to doing this safely.

Do not create a giant hierarchy for appearance. Begin with one folder and a few files containing real information, and let the structure grow in response to actual work.

Nested context. You may have one broad personal-os/ folder, a work area inside it, and individual project folders inside that. When working on a specific project, open your coding agent in the project’s folder, not the top level — the agent gets that project’s files and instructions as its immediate context instead of starting from your entire life. Keep confidential or unrelated material outside any folder you hand to an agent.

3. Setting up your AGENTS.md

AGENTS.md is a plain markdown file at the root of your Personal OS that agents read automatically when they start working there (Claude Code also reads CLAUDE.md; the common convention is to keep one AGENTS.md and have CLAUDE.md simply point at it). It is durable local guidance: the terrain, the goals, and the working conventions.

A good AGENTS.md answers four questions:

What is this place? A few sentences: “This is my Personal OS — the home for my projects, plans, data, and context. Agents working here should…”
What lives where? A short map of the directory structure. Not a full file listing — a guide to where each kind of thing goes, so the agent knows both where to look and where to put new work.
How should agents behave here? Your conventions: how you like to be addressed, what needs your approval, where new artifacts should be saved, what must never be committed.
How does the system stay maintained? Instruct agents to update the map when they add something new, so the AGENTS.md stays true as the system grows.

The best way to create it is not to design the whole system upfront — it’s to let your agent interview you. From class, the starting prompt:

Hey, can you make a folder in my home directory called personal-os, then help me fill in an AGENTS.md by interviewing me about what I want this personal operating system to be?

I want it to be a comprehensive place for all my work, projects, data, goals, intents, prompts, skills, learnings, plans, and files.

I want agents to maintain a map to all its different parts so they always know how to navigate the project.

The system should grow through use. A maintained map is more important than copying everything into one directory immediately.

4. Syncing your Personal OS across all your devices

The goal: when you add a file on your laptop, your Zo computer sees it; when your Zo agent writes a report overnight, your laptop has it in the morning. Both local and cloud agents work from the same evolving system.

The professional-grade way to do this is Git + GitHub — the same tools that sync code for every software team on earth. If Git is new to you, read the Git reference guide first; here is the shape of the setup:

Turn your Personal OS folder into a Git repository. In a terminal, inside your personal-os folder: git init. (Or ask your agent: “Turn this folder into a git repository.”)
Create a private GitHub repository and connect it. Install the GitHub CLI, log in with gh auth login, then gh repo create personal-os --private --source=. --push. Private matters — this is your life’s context, not open source.
On every other computer, clone it. On your Zo computer (or any machine): gh auth login, then gh repo clone <your-username>/personal-os. Now that machine has a full copy.
The sync loop. After working on any machine: commit and push (git add -A && git commit -m "what changed" && git push). Before working on any machine: pull (git pull). Or simply tell your agent “commit and push my personal OS” / “pull the latest” — this is one of the most reliable things to delegate.

A few habits make this painless:

Pull before you start, push when you stop. Machines that both edit the same file between syncs create conflicts; the pull-first/push-after habit avoids nearly all of them. If a conflict happens anyway, ask your agent to resolve it — this is routine work for a coding agent.
Use a .gitignore for what shouldn’t sync. Secrets files and heavy media are the classic entries (the Git guide shows how).
Let agents do the mechanics. You need to understand the loop (edit → commit → push → pull elsewhere); you do not need to memorize the commands. Every coding agent knows Git deeply.

Once this is in place, the same repository lives on your laptop, your Zo computer, and anywhere else you work — and GitHub becomes the shared meeting point. This also unlocks a powerful pattern: agents on different computers collaborating through the repo. One agent (say, ChatGPT or your local Codex) writes a plan and pushes it; your Zo agent pulls the repo, finds the plan, and executes it. The Personal OS becomes the shared workspace where your whole fleet of agents coordinates. The Zo Computer guide covers this in detail.

Advanced

5. Secrets and heavy media: in the folder, out of the repo

The rule from section 2 was “keep secrets and heavy media out.” The refined version: keep them out of the repository — the synced, remembered-forever part — while still letting them live in the folder where your agents work. The tool for this is .gitignore (introduced in the Git guide): a file listing patterns Git must never track. An ignored file sits in your Personal OS like any other file — agents can read it, scripts can use it — but it is never committed, never pushed, and never appears on your other machines.

Storing secrets. Give secrets one well-known, ignored home instead of scattering them:

Create a single file for keys, e.g. .secrets (or .env) at the root of your Personal OS, one NAME=value per line:
```
OPENAI_API_KEY=sk-...
RESEND_API_KEY=re_...
```
Ignore it before you write anything into it. In .gitignore:
```
.secrets
.env
```
Verify with git status — if the file shows up as new/untracked, the pattern is wrong; fix it before committing anything.
Tell your agents about it in AGENTS.md — this is what makes the keys usable without being visible:

API keys live in .secrets (git-ignored, this machine only). When a script needs a key, read it from there by name. Never copy a key’s value into any other file, any committed file, or any chat output. When a new secret is added, note its name and purpose here — never its value.

The agent can now run tools that need your keys, and the durable record (the AGENTS.md table of names and purposes) syncs safely while the values stay put.
Because ignored files don’t sync, each machine needs its own copy. That is a feature, not a bug: secrets should travel through a secure channel (a password manager, or typing them in once per machine), never through GitHub. On your Zo computer, recreate the file once and it’s set.

Two cautions. First, .gitignore prevents future tracking — it does not scrub history. If a key was ever committed, treat it as exposed and rotate it. Second, ignored is not encrypted: anyone (or any agent) with access to that machine’s files can read it. For higher-stakes credentials, graduate to your operating system’s keychain or a secrets manager — but the ignored-file pattern is the right starting point, and vastly better than keys pasted into prompts or committed files.

Storing heavy media. Same trick, different motive — here the goal is keeping clones fast, not confidentiality:

Keep media in a dedicated ignored location, either by extension or by folder:
```
*.mp4
*.mov
*.wav
media/
```
Commit the small text that makes the media findable and reproducible: an index (media/INDEX.md — what exists, where it came from) and, where possible, a download script that can re-fetch the files from their source (cloud storage, YouTube, an archive). A newly cloned machine gets the map immediately and can regenerate the bytes on demand.
If a machine doesn’t need the media at all (your Zo computer rarely needs your raw video), simply never download it there. The repo stays identical everywhere; the heavy payload lives only where it’s used.

The general principle behind both patterns: the repository syncs the map; each machine holds only the territory it needs. Secrets and media are just the first two cases — the same move works for anything too sensitive or too heavy to push.

Even more advanced: a sync script for the untracked files

Sometimes you do want the ignored files on more than one machine — your media library on both your laptop and your Zo, your .secrets recreated without retyping. You can sync them directly, machine-to-machine, without Git or GitHub ever touching them.

The workhorse is rsync, a standard tool that copies only what changed, over the same SSH connection you set up in the Zo guide. A minimal sync-private.sh at the root of your Personal OS:

#!/bin/bash
# Sync git-ignored files directly to my Zo (over SSH — encrypted, no GitHub involved).
rsync -av .secrets zo:/home/workspace/personal-os/.secrets
rsync -av media/   zo:/home/workspace/personal-os/media/

Run it after the ignored files change (./sync-private.sh), and the private layer travels laptop → Zo directly while the repository keeps syncing the public layer through GitHub. Notice the pleasant recursion: the script is small, contains no secret values, and belongs in the repo — so every machine knows how the private layer moves, even though the private layer itself never touches Git.

Three notes to keep this safe and sane:

The transport is the point. SSH is encrypted end-to-end between your machines — that’s what makes it an acceptable channel for secrets where GitHub (a third party, with history) is not.
Pick one direction, or be careful. The simple script above pushes laptop → Zo, making the laptop the source of truth for private files. Two-way syncing of changing files is where data gets clobbered; don’t add --delete or reverse-direction lines until you’ve thought it through.
Have your agent build yours. This is a perfect delegation: “Write me a sync-private.sh that rsyncs my git-ignored secrets and media folder to my Zo over SSH, laptop-as-source-of-truth, and add a line to AGENTS.md documenting it.” The agent knows rsync’s flags; you just need to know the shape of what you asked for.

Practice

Create your personal-os folder and run the interview prompt above to produce your first AGENTS.md.
Move one real project into it: a folder with a short brief (goal, constraints, current status) and whatever files exist so far.
Save one durable context file from a recent agent conversation: ask the agent to summarize the goal, decisions, and next steps into a file in the project folder.
Set up sync: initialize Git, create the private GitHub repo, and push. Then clone it onto a second machine (your Zo computer is the natural choice) and verify a test change travels both directions.
Open a fresh agent session pointed at your Personal OS and ask: “What am I working on right now, and what should I do next?” If the answer is wrong or empty, that reveals what your map is missing — fix the map, not the agent.
(Advanced) Set up the secrets pattern: create .secrets, ignore it, verify with git status that Git can’t see it, document it in AGENTS.md, then ask your agent to use one of the keys for a real task without ever printing its value.
(Advanced) Once SSH to your Zo works, have your agent write sync-private.sh and run one round trip: change an ignored file locally, sync it, confirm it arrived on Zo — and confirm it never appeared in git status on either machine.

Proof of understanding

What is the difference between context in a chat thread and context in your Personal OS? Why does the difference matter when you switch tools or devices?
Your Personal OS should be “a map, not a warehouse.” What does that mean, and why is it kinder to the agent’s context window?
Name three things that belong in a Personal OS and three things that must never go in one. Why is each exclusion dangerous?
What four questions should your AGENTS.md answer?
Walk through the sync loop: you edited files on your laptop this morning and want to work from your Zo computer tonight. What has to happen, in what order, on which machine?
Why should the GitHub repository be private?
What is the difference between “in the folder” and “in the repository”? How does .gitignore create that difference, and why does it let an agent use your API keys without leaking them?
Your .secrets file needs to exist on your Zo computer too. Why must it travel there by SSH (or retyping) rather than through GitHub — and why is it fine that sync-private.sh itself is committed?