Life in a repo

For about a year now, most of my life admin has lived in a git repository. Not my code — my life. Financial decisions, training plans, career notes, the paperwork that accumulates around a household, side project ideas that will mostly never happen. It started as a folder of markdown files and slowly turned into something closer to an operations repo: a linter, CI checks, scheduled jobs, and an AI agent that knows its way around.

This post is about why that setup works, the design decisions behind it, and what changes when you point a coding agent like Claude Code at a repo that contains no code.

why plain text, why git

The case for plain text is old and still correct. Markdown files will outlive every app you currently use. They diff, they grep, they sync anywhere, and there's no export button to worry about because there's nothing to export from.

Git adds the part note-taking apps never get right: history with intent. A sync service tells you a file changed; a commit tells you why. When you're tracking decisions that play out over months (fix the rate or not, is this side project worth the evenings), being able to see what you knew and thought at the time is genuinely useful. Six months on, you won't remember the reasoning. The commit does.

There's also a practical benefit: git gives you multi-device sync for free. Every device is just a clone pushing to the same remote — no proprietary sync service, and when two devices disagree you get a merge conflict, which you already know how to deal with.

                  ┌───────────────┐
                  │    GitHub     │
                  │   (the hub)   │
                  └───────────────┘
                    ▲     ▲     ▲
        push / pull │     │     │
        ┌───────────┘     │     └───────────┐
        ▼                 ▼                 ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│    laptop     │ │     phone     │ │ cloud session │
│editor + agent │ │ Obsidian + git│ │  agent only   │
└───────────────┘ └───────────────┘ └───────────────┘

And then the reason I didn't see coming: a repo is the native habitat of AI coding tools. They already know how to read a tree of files, search it, edit it and commit. They don't care that the files describe an insurance renewal rather than a service.

the shape of the thing

There's a whole cottage industry around personal knowledge management (PKM). Zettelkasten, PARA, digital gardens, endless videos about linking your thinking. I read a fair amount of it and ended up ignoring most of it.

The structure that survived contact with real life is boring: top-level folders named after areas of life.

/
├── CLAUDE.md          # how the system works, for the agent
├── SNAPSHOT.md        # where everything stands right now
├── ACTIONS.md         # what needs doing this week / month
├── LOG.md             # dated record of sessions + decisions
├── decisions/         # settled questions, with revisit triggers
├── finance/
├── work/              # career strategy, not employer material
├── health/
├── home/
├── projects/
├── learning/
├── scripts/           # linter, analysis, dashboard
└── templates/

That's deliberate. When you're filing something quickly at the end of a long day, you want an obvious home for it, not a clever one. Every clever structure I tried decayed within weeks. The boring one is still standing.

A few structural decisions matter more than the folder names:

One repo or several. I keep one repo for personal life and a separate private one for detailed work notes, on the work machine, where it belongs. That boundary is contractual as much as organisational. One life repo is right for most people; the moment employer IP starts creeping in, split.

What stays out of git. Bank statements, signed contracts and anything with account numbers are gitignored. What makes this workable is committing derived data instead: a categorised spending summary is useful and safe to track; the raw statement it came from is neither. The repo should know your patterns, not your account numbers.

Where the trust line sits. Be honest about what this setup is: a private repo on someone else's servers, read by a model provider every time an agent session runs. No amount of gitignore changes that. I decided the patterns and the reasoning are a trade I'll make for the leverage — they're roughly as sensitive as what already sits in my email — and the credentials and raw documents are not, which is exactly the line the gitignore enforces. Yours may sit somewhere else. The only bad version is the one where you never noticed you were making the decision.

The editing surface. I use Obsidian on top of the repo, mainly for mobile access and wiki-links. But it's a view, not a dependency. Everything works from a terminal, which matters more than I expected.

the interesting part

A repo full of markdown is a perfectly good codebase as far as Claude Code is concerned.

The first time I opened a coding agent inside my notes, I used it as a search engine. Find that thing I wrote about the renewal. Summarise where the pension decision got to. Useful, but shallow. The shift came when I started treating sessions as work sessions: sit down with a vague pile of life admin, leave forty minutes later with decisions written down, files updated, and a commit history describing what happened. The same loop I'd run on a codebase: read the context, make the change, commit with a message that explains it.

But an agent walking into your life cold is a new joiner on day one: capable, and completely lost. Everything useful about the setup follows from taking that onboarding problem seriously.

onboarding documents for a machine

What works for me is a small set of files that exist purely to give an agent (or a future me, same thing) context fast:

The snapshot is state, not history: what you'd tell a friend who asked how things are going. The log is not a diary; it's closer to an engineering decision log, and its main job is stopping the same discussion from happening twice. And CLAUDE.md is the README your agent reads before touching anything. Writing it forces a useful question: if you can't explain your own system to a machine in a page, you probably don't have a system.

None of this is really an AI pattern. A status page, a backlog, a decision log, a README: it's what any well-run team keeps. Making your life legible to an agent and running it like a documented project turn out to be the same activity.

recipes and decisions

The most useful distinction I've found is between things that are recipes and things that are decisions.

Recipes get written down as exact procedures and the agent follows them literally. No creativity wanted. Wrap them in slash commands and "log this" becomes a one-liner.

Decisions get the real thinking, and the outcome gets written to a decisions folder with a revisit-when trigger: revisit if rates drop below X, revisit when the fixed term ends. Settled questions stay settled until reality actually changes. Without this you re-derive the same conclusions every few months, which is what thinking without version control looks like.

If you take one idea from this post, take that one. Most productivity systems fail because they treat everything as one kind of work. Splitting the mechanical from the judgement-heavy, and giving each its own tooling, is what made this sustainable.

treating notes like code, all the way down

Once the repo mattered, I reached for the tools I'd use on any codebase that mattered:

A linter. Structured notes (races, subscriptions, trips) have frontmatter schemas, checked by a small Python script. That sounds excessive for personal notes, until an agent has written a hundred of them and you'd like them consistent.

CI. A GitHub Action checks for broken internal links on every push. Cheap to set up, catches rot forever.

Scheduled jobs. A weekly review runs on a schedule in a fresh remote session, and the output arrives as a pull request:

Sunday, on a timer
        │
        ▼
fresh agent session
        │
        ▼
reads the week's log, actions, activity
        │
        ▼
review written, pull request opened
        │
        ▼
me, reviewing my own week like any other PR

The point isn't automation for its own sake. It's that reviews happen, which they reliably didn't when they depended on Sunday-evening willpower.

None of it is needed on day one, but it compounds.

what didn't work

Daily notes, the cornerstone of most PKM advice, died completely. I never wrote them, felt vaguely guilty about it, and the empty files became noise. I deleted the ritual and made sessions the unit of record instead: things get logged when work actually happens, at whatever frequency that is. If your evenings aren't reliably your own, anything in the system that depends on daily discipline is a part that will fail. Design for bursts.

Elaborate tagging and linking schemes went the same way. Search is good now and agents are better; findability comes from decent filenames and an honest folder structure, not metadata you'll never maintain.

The system also needs pruning like any codebase. Files go stale, structures stop fitting, old experiments linger. I do the occasional housekeeping session (with the agent, naturally) the way you'd pay down tech debt.

starting smaller than I did

If any of this appeals, don't build my setup. Build this:

1. A git repo with folders named after your life areas.
2. Three files: a snapshot of where things stand, a list of what needs doing, a log of what you decide.
3. A CLAUDE.md explaining the above to an agent.

Then open Claude Code in it and do one real piece of life admin end to end. Pick something with an actual decision in it, not just filing. If the session ends with updated files and a commit message that would still make sense to you in six months, you'll see why the rest of the machinery eventually follows.

The repo isn't the point. The point is that the thinking you do about your own life stops evaporating.