Files, Agents, and the Future of BaseHub

Last week, the CMS industry was shook by Lee Robinson’s post on how Cursor migrated away from a headless CMS to markdown and git. Interestingly, we’ve been heads down working on something that will bring the best of both worlds to content management. While there’s still a bit of development work left for us before a release, we wanted to share our vision with you today.

Key Points

1. We’re re-architecting the core of BaseHub to bet on more foundational technologies (the file system, Git, coding agents), so we can innovate where it really matters (UX & DX).

2. We’ll be open sourcing BaseHub Core. Anyone will be able to self-host BaseHub, and developers will be able to contribute. Notably, we don’t plan on open sourcing basehub.com, but rather, an extracted Core for anyone to self-host or run offline.

Betting on Git and the File System

BaseHub started with an ambitious vision: to bring Git-like versioning and collaboration to content management. Early on, we decided we wouldn’t leverage Git: we thought “files on Git would be too hard to scale.” So we built BaseHub on top of Postgres and a home-cooked version of Git’s data-model that ran on it.

While this was, in many ways, a really cool architecture—we deeply studied how Git internals work and invented our commit and branching systems—it meant spending a lot of time fixing bugs and building new features that Git already had. And because Postgres was powering it all, our data model and SQL queries got really complex.

And then came the coding agents, and the fact that they’re incredible at working with files and Git. Huh. We started doing more and more work with Cursor and Claude Code. We were amazed at how great they were at helping us do more work, while still keeping the quality bar high. Our codebase was big and complex, and yet the agents would read and grep and navigate the file tree effortlessly.

We couldn’t bring that to BaseHub. Not because “LLMs are good at writing code but bad at prose,” as we didn’t believe that to be true. It was the environment that made the difference.

So we're going back to basics. Real Git. Real files. Right next to your code.

your-app/
  .basehub/
    homepage.bshb
    blog-posts/
      my-first-post.bshb
      my-second-post.bshb
  src/
  package.json

Letting Agents Loose

As we built our own in-app AI Agents, we struggled to explain to them how to interact with our APIs. Unless we used the very best models with carefully crafted tool descriptions, there was no chance of success. Our “harness” was doomed to fail.

We want to change that. If the file system is home for agents, we want to meet them there. Concretely, this means:

• Content will be stored in a Git repo, under a .basehub directory

• We're designing our file-based data model on top of Markdoc, which is more flexible than markdown while preserving the familiar syntax

• Content editing will happen in basehub.com, as well as in any IDE or remote coding agent—anything that talks Git

The Best of Both Worlds

Git is the best collaboration tool for knowledge work—it just hasn't been used for content because the tooling wasn't there. With the right interfaces, anyone can collaborate on content that lives in a repo. Branches, PRs, version history, etc… these aren't just for developers anymore.

But raw markdown falls short when you need structure, validation, and querying. That's why we're not just building "markdown files in Git." We're building on top of all the infrastructure that got us here.

• For developers: Real Git. Real branches. Real PRs. Edit in Cursor, Claude Code, v0. Zero signup to start.

• For content teams: A beautiful editing UI on basehub.com. Roles, real-time collab, and a more visual editing experience. All the things that make a CMS useful.

---
title: Homepage
type: document
---

{% text title="Hero Title" value="Welcome to BaseHub" /%}

{% richText title="Hero Description" %}
  The best of both worlds: **Git-native** content that anyone can edit.
{% /richText %}

{% component title="CTA" %}
  {% text title="Label" value="Get Started" /%}
  {% text title="Href" value="/signup" /%}
{% /component %}

Open Sourcing BaseHub Core

We want to make basehub as ubiquitous as sqlite. We want developers to start using BaseHub without signing up to anything—fully offline. Not being open source doesn’t make sense if we’re serious about this.

We want the community to help us shape the product. We’re built on open source technologies and we understand the magic that comes with it.

We’re a small company, so having an open source, auditable codebase, allows us to target larger customers. These customers will either use our cloud (basehub.com) or self-host. We won’t have opinions there, but we’ll be there to help.

What's Next

We're still in active development and will release as soon as we have something meaningful to show. We’re working on finalizing the file format, building out the open source components, testing the migration path. We wanted to share our vision now because the timing felt right.

More soon!

FAQ

If content lives in the same Git repo as my app: does every content change trigger a full rebuild?

By default, yes. Builds will happen with the data that’s right there, in your repository. That being said, for platforms like Vercel and frameworks like Next.js, rebuilds won’t be required, thanks to ISR and ignoreCommand .

Content updates flow through our CDN and your app picks them up via ISR.

// vercel.json
{ "ignoreCommand": "git diff HEAD^ HEAD --quiet .basehub/" }

Alternatively, you’ll be able to store the content in a separate Git repository, which would avoid this issue altogether.

Why Markdoc instead of MDX?

MDX is powerful but it blurs the line between content and code—you're writing JSX inside your content files. Markdoc keeps content as content while still allowing custom tags and validation. It's more constrained, which makes it easier for non-developers to edit and for agents to parse reliably.

Can I use BaseHub without basehub.com?

Yes. The core will be open source and run locally. You’ll be able to npm install basehub, init a .basehub directory, and start editing without creating an account. The cloud will be optional—providing CDN delivery, a collaborative editing UI, and team features—while the local-first experience will work on its own.

What happens to my existing BaseHub content?

We'll handle this. The new architecture will be fully backwards compatible.