The Home Repo

What happens when a software architect applies professional AI-agent patterns to running a household. An experiment in git, markdown, and letting agents operate, not just read.

I build software systems for a living. For the last couple of years, a large part of that work has been figuring out how to make AI agents effective inside professional codebases: structuring context so agents can navigate, reason, and act without a human holding their hand.

At some point I started wondering: what would happen if I applied the same patterns to my personal life?

Not as a productivity experiment. Not as a second brain. Just: what if I had a repo that knew about my household, my finances, my property, my contracts, and an AI agent that could operate on it?

So I created a git repo called home, and started using it.

The setup is boring

I want to get this out of the way because it is the least interesting part.

It is a git repository. It contains markdown files organised into folders. There is a CLAUDE.md at the root that gives the agent context about the repo, the household, and how things are structured. Git LFS is enabled so PDFs, scans, and invoices live alongside the markdown that describes them.

That is it. There is no app. No database. No custom tooling. If you have used a static site generator or a docs-as-code setup, you have seen this before.

The structure is not the point.

The inbox

The hardest part of any knowledge system is getting things into it. If filing a document requires deciding where it goes, naming it correctly, and writing a summary, you will not do it. You will leave it in your email or your downloads folder and deal with it never.

So the repo has an inbox. It is just a folder, a drop zone with no rules. Anything that arrives gets dumped in: scanned post, digital documents, email attachments. My wife and I share a Google Drive folder for this. Scan something with your phone, drop it in, forget about it. Flagged emails work the same way: flagging is the only action needed.

When I have time for admin, I ask the agent to process the inbox. It opens each item, identifies what it is, suggests where it belongs, files it, and writes a summary. The human effort is: scan, drop, move on. The agent does the filing.

This is the pattern that makes the whole system sustainable. Capture is near-zero effort. Processing is batched and agent-driven. The inbox separates the moment something arrives from the moment it gets dealt with, and that separation is what makes the whole thing actually work in practice.

It is all conversation

I want to set expectations before showing what the repo looks like now, because it would be easy to read the rest of this post and think I sat down and engineered a system. I did not. Everything in this repo emerged from conversations with an AI agent.

Every interaction is a dialogue. I have a problem (an email to respond to, a tariff to check, a contract to find), and I talk it through with the agent. The agent researches, drafts, pulls in documents, answers the question. That is the primary track: getting the thing done.

But every conversation has a second track. While we are solving the problem, the agent is also suggesting how to organise what we have found. Where should this go? Is there an existing section or do we need a new one? Sometimes I guide it, sometimes it suggests something better than I had in mind. “You have three insurance policies that reference this property. Should I consolidate them into a single summary?” I would not have thought to do that. The agent spotted the pattern.

The two tracks are not separate. They happen in the same dialogue, often in the same sentence. This is not overhead. It is just how the conversations go.

The result is that the repo grows and improves as a byproduct of using it. Nothing you will read below was planned or designed upfront. It all came from conversations.

What is the point

The point is what happens when an AI agent can not just read a knowledge base, but operate on it. Build it. Maintain it. Act on what it finds.

Here is a concrete example.

A few weeks ago I got an email from an architect asking me to sign a contract. I had been working with this architect for a couple of years, but there was nothing about them in the repo yet. No context. No history.

So instead of manually digging through email, I asked Claude to go through all my correspondence with this architect (every email, every attachment, every invoice, every document) going back two years. Organise the documents. Create a correspondence log. Write a markdown summary of everything: the project timeline, what was agreed, what was invoiced, what is outstanding. File it all in the repo.

Then draft a response to the email, using that context.

Here is the part I did not expect. While sweeping through the correspondence, the agent found that we had already signed that exact contract, six months earlier, in October. I had forgotten. The agent drafted a polite reply, attached the signed copy, and pointed out the duplicate. Without the sweep, I would have signed the same contract twice, using a lot of unnecessary cognitive effort.

Twenty minutes of work. A complete history of the relationship, properly organised, every document filed and linked, a draft reply, and a mistake caught that I would not have caught myself.

The next time something comes in from that architect, the context is already there. No digging. No remembering. The repo knows.

That is the pattern. Not “file things neatly.” It is: every question you ask grows the knowledge base, and the knowledge base makes the next question easier.

You do not fill it. You grow it.

The instinct (and this is the instinct that kills every personal knowledge base) is to sit down and backfill everything. Catalogue all your insurance. Index every appliance warranty. Transcribe every contract.

Do not do this. You will burn out in a weekend and never open the repo again.

Instead, let real questions drive it.

“Am I on the right solar tariff?” That was a real question I had. So I asked Claude to scan my email for all solar correspondence and attachments. The recent install was well covered, but the old panels (the ones already on the house when I bought it) were missing. Those documents were buried in the property purchase folder on Google Drive. So I copied the whole purchase folder into my inbox and asked the agent to organise it into the property section as a side task, then carry on with the solar thread.

Now I have a solar section I never planned, and a properly organised property section I never sat down to build. Both came from one question about tariffs.

Succession notes. What happens if I am unexpectedly not around: how to access stuff, where to find things, who to contact. That is in there too. Not because I had a morbid weekend of planning, but because the question occurred to me one evening and it took fifteen minutes to get a first draft into the repo.

The repo accretes like a coral reef. Each question leaves behind a little more structure. Over six months, it becomes genuinely useful without anyone having planned it.

The patterns that emerged

Here is where the software architecture background becomes relevant. Not because I designed these patterns into the repo, but because I recognised them after they appeared.

When you work with AI agents professionally, you learn that certain patterns make agents dramatically more effective. Structured context. Explicit boundaries. Repeatable workflows with documented decisions. These are not AI-specific ideas. They are just good engineering practices that happen to matter more when the operator has a context window instead of a career of institutional knowledge.

Several of those patterns showed up in my home repo through conversation, without anyone planning them.

Runbooks

In a professional setting, a runbook is a step-by-step procedure for a repeatable operation: deploying a service, handling an incident, onboarding a customer. The documentation is the procedure. An agent reads it and executes.

In my home repo, the same pattern emerged for quarterly accounts. Through several quarters of doing VAT filings together, the agent and I built up a markdown file that describes the full process: which bank statements to pull, how to categorise expenses, what goes to the business entity versus self-employment, what needs to be uploaded to the tax authority. The agent reads it and follows it.

Critically, each step is marked as either fully automatable or requiring human input. “Bank statement classification: agent.” “KBC security confirmation: Paul’s keyboard.” This is a human-in-the-loop contract expressed in prose, something I have designed into professional systems but never expected to use for my household accounts.

Decision tables

Every quarter, the agent doing my accounts hits judgment calls. Is this Broadband bill a business expense? What percentage? What about the home office deduction?

Early on, it asked me every time. After the second quarter of the same questions, the agent suggested we lock the recurring decisions down. We worked through the edge cases together, and it wrote the table:

Now the agent reads the table and applies the rules. No “are you sure?” loops. I made the calls. The agent wrote them down, and keeps the table maintained. When a new edge case surfaces, we resolve it and it adds a row, locked down so it never comes up again.

This is a pattern I have not often seen articulated in any AI tooling. It is somewhere between a config file and a policy engine, but it is neither. It is just a markdown table that a human can read and an agent can follow. Durable delegation in prose.

Supplier playbooks

I have a file that documents how to download invoices and statements from nineteen different suppliers. I did not write it. The agent did, by doing.

The first time I needed Amazon invoices, I pointed the agent at Amazon and said “download everything.” It spent a long time figuring it out: navigating the UI, hitting dead ends, discovering that the invoice popover requires a real click rather than a programmatic one. When it was done, I asked it to write back what it had learned into a playbook. Next time, it follows the playbook instead of rediscovering the process from scratch.

Nineteen suppliers later, the file contains exact URLs, download steps, naming conventions, and the specific gotchas (the part that takes the longest to accumulate). Chrome blocks multi-downloads from Coolblue. GoDaddy does not offer PDF export at all, so the agent reconstructs receipts from extracted text. Each entry is hard-won knowledge that the agent earned by trial and error and then documented for its future self.

The same feedback loop, again: attempt, learn, write it down, improve next time. I am not doing the learning. The agent is. I am just asking it to remember what it learned.

Where it is going

The repo is six months old. It is not finished (it will never be finished), but it is already at the point where I reach for it instinctively when a question comes up about the household, finances, property, or admin.

I am considering adding a vector database with an MCP interface, so that as the repo grows, search can scale beyond grep and agent context windows. That is a future problem. Right now, structured markdown and a good index file are more than enough.

I am experimenting with GitHub issues as a task queue for outstanding actions, another professional habit following me home. The repo is the knowledge base, issues are the to-do list, the agent is the worker that connects them.

I am also experimenting with more sentimental content. Historical dates, family milestones, past holidays. The kind of information that is not urgent but is surprisingly pleasant to have at your fingertips. “What year did we go to Spain?” is a question I should not need to scroll through photos to answer.

How to start

If any of this sounds useful, here is what I would suggest:

Do not plan. Do not design a folder structure. Do not write a schema. Do not spend a weekend “setting up.”

Create an empty git repo. Enable Git LFS. Add a CLAUDE.md that gives the agent basic context: who you are, what the repo is for, how files should be named. Create an inbox/ folder for dumping documents.

Then wait until you have a real question.

When you do, ask the agent to help you answer it. Let it pull in documents, write summaries, organise files. When it is done, you will have the beginnings of a knowledge base, not one you designed, but one that grew from an actual need.

Next question, same thing. And the one after that.

Six months from now, you will have a repo that knows a surprising amount about your life. Not because you filed things diligently, but because you kept asking questions and letting the answers accumulate.

I have been writing about the patterns that make AI agents effective in professional software: boundaries, security, structured context. This post is the same ideas applied to a different domain. The principles transfer. The formality does not. And that is rather the point.