The Repo-Native Manifesto

The one-paragraph version

Your company already has a database that is versioned, distributed, offline-first, auditable, permissioned, and understood by the developers and agents working in it. It is called a git repository. Repo-native software keeps the source of truth in plain files inside the repo: todos, content, plans, email history, the map of what you have built. Every app, dashboard, and service is a view of those files, never their owner. When the truth lives in files, humans edit it with any editor, agents operate on it with the tools they were trained on, and history is git log. No vendor owns the record.

Why now

For twenty years, “put it in a SaaS” was the right call. Jira, Notion, Mailchimp, Contentful: each one traded ownership for convenience, and the trade was worth it because humans are bad at maintaining structure in raw files.

Agents flipped the trade.

An AI agent is good at exactly the thing SaaS existed to compensate for: reading, writing, cross-referencing, and maintaining structured plain text at scale. And it is bad at the thing SaaS requires: navigating a bespoke web UI or learning a proprietary API with auth flows, rate limits, and pagination quirks.

Concretely:

• To let an agent manage todos in Jira, you configure an API token, install or build an integration, teach the agent the Jira data model, and pay per seat. To let it manage todos in a TODO/ directory, you say: “the todos are in TODO/.” It already knows grep, cat, and markdown. The integration cost of a file is zero.
• An agent that drafts a blog post in a headless CMS needs a custom tool. An agent that drafts a blog post in content/posts/ needs a filename.
• When an agent makes a mistake in a SaaS, you find out from an angry customer. When it makes a mistake in a repo, you find out from git diff, before you merge.

Pull requests give humans a review boundary around agent labor: an agent can do work overnight, and a human can review the diff in the morning.

The thirty-year arc

Each of these was once a separate system with its own UI, its own database, and its own export button. Each one migrated into the repo, and nobody went back:

The pattern repeats because the repo keeps winning on the same four properties: diffable, reviewable, versioned, ownable. Repo-native is not a new idea. It is the next chapter of an idea that has been winning for thirty years.

The invariants

A tool is repo-native when it holds these lines. They are lifted from real shipped products; RepoTodo enforces every one of them today.

1. The files are the truth. Nothing is stored that cannot be recomputed from the files. Delete the tool; your data is still complete, readable, and editable.
2. The data and the services are loosely coupled. Swap the blog renderer, the dashboard, or the mail sender; the record stays put. Derived state is computed on read, from files plus git history.
3. Byte-preserving writes. A no-op write is byte-identical. The tool never reformats, reorders, or “cleans up” a file the user did not ask it to change. This is the trust boundary: a tool that rewrites your files uninvited is a tool you cannot let near them.
4. Nothing is required. Missing frontmatter, loose checkboxes, an unconfigured repo: the tool warns; it never blocks. Plain markdown written by someone who has never heard of the tool must still work.
5. One record shape, many surfaces. CLI, dashboard, MCP server, SDK, and HTTP API are all thin views over the same operations on the same files. No surface has private state.
6. Graceful exit. Adopting the tool must not be a commitment. Stop using it and you are left with a well-organized folder of markdown.

Repo-native can be DIY, open source, hosted, or a mix: hand-edit the files, run an open-source CMS, or pay for a hosted view. Each operates on the same record, so the choice is per-tool and reversible.

What it costs

The record layer is free: the files and their history live in the repository you already keep, and you already pay for a git host. You pay only at the edges (hosting, delivery, a managed dashboard, or another service you choose), and those services are swappable without migrating the record.

• History and provenance. git log --follow on any todo, post, or plan is a complete audit trail with author, timestamp, and diff. Jira sells this as an audit-log add-on.
• Review workflow for everything. A blog post ships as a PR. A roadmap change ships as a PR. Suggestions, inline comments, approval gates: your content gets the machinery your code already has.
• Branching reality. Draft an entire alternate content calendar on a branch. Merge it or delete it. Your SaaS probably cannot show you a diff of this quarter’s plan against the current one.
• Offline, and fast. The truth is on disk. A scan of a 5,000-file repo resolves in under 100ms locally; no spinner, no session timeout, no status page to check.
• Backup and migration are the same word. git clone. Onboarding a new teammate or a new agent is also the same word.
• Loose coupling. Repo-native tools compose through the filesystem. The todo tool can see the blog folder; the portfolio dashboard can read the todo queue. No webhooks, no Zapier, no OAuth handshake between your own tools.
• Permissionless tooling. Anyone, human or agent, can write a script against files. Nobody can write a script against a SaaS without an API key and an approval.
• No per-seat or per-agent pricing. A file does not know how many people or agents open it. You pay for a service where you choose one, not for access to your own records.

A ten-person startup running task, docs, content, email, and internal-tool systems across separate SaaS products gets several sources of truth, several subscriptions, and several integration credentials. The repo-native version is one repository, a handful of directories with conventions, tools that render them, and services only at the edges. The truth count is one.

What repo-native is NOT

The boundaries matter:

• Not anti-cloud. Services still render, serve, send, and compute. A Cloudflare Worker serving your blog is repo-native as long as the source of truth it renders from is the repo. The rule is about who owns truth, not where compute runs.
• Not markdown fundamentalism. Tinbox stores email in the repo; email is not markdown, and that is fine. The thesis is repo-native: files, git, recomputability. Markdown is the lingua franca, not the law.
• Not for everything. Secrets do not belong in files in a repo. Realtime collaborative cursors, high-volume analytics events, payment processing: wrong tool. Repo-native claims the system-of-record layer, not every layer.
• Not a sync engine. Git’s merge model is the collaboration model. If a workload needs operational transforms and live multiplayer, it is not a repo-native workload. Asynchronous, PR-shaped collaboration is the point, not a limitation.
• Not “just files” naïveté. Plain files without conventions rot. The value is files plus conventions (formats, IDs, frontmatter) plus tools that respect the invariants above. The convention layer is exactly what repo.md exists to standardize.

Low human, high agent

The end state repo-native builds toward: one person directing a fleet of agents, with the repo as the shared workspace and git as the safety rail.

• The human’s job collapses to direction and review: write the task file, read the diff. Everything between is delegable.
• Agents do not need accounts, seats, or invitations. They need a checkout.
• Handoff between agents is free, because state lives in files, not in a session. Agent A drafts, agent B critiques, agent C fixes the links. The repo is the message bus.
• The org’s memory survives every tool change, every model upgrade, and every employee departure, because memory was never in the tools.

A company run this way can be smaller and more auditable than the SaaS-sprawl company it replaces. Every action an agent takes is reviewable as a commit.