Imagine a project management tool that works perfectly offline, never locks you into a cloud, and lets you see, tweak, and move every piece of data just by opening a folder on your disk. That’s what Threlmark does. It treats your local storage as the ultimate source of truth, flipping the usual cloud-first approach on its head.

In this article, you’ll see how this simple idea drives complex benefits—speed, privacy, flexibility—and how it makes AI collaboration smarter. If you’re tired of cloud lock-in and want a system that’s truly yours, stick around.

Key Takeaways

• Threlmark treats disk files as the source of truth, making data portable, inspectable, and restartable without a database.
• Atomic file operations prevent corruptions, enabling safe concurrent edits across devices.
• One file per item simplifies sync and conflict resolution, supporting real multi-device collaboration.
• Local-first design improves speed, offline access, and privacy—your data stays with you.
• External tools and AI agents can participate effortlessly by reading and writing shared files, no permission hoops.

Why Your Disk Is the Real Contract, Not a Cloud Database

Threlmark’s core idea is simple but revolutionary: the files on your disk are the only source of truth. No backend server, no remote database—just your folder full of JSON files. This means every change is a direct edit, and everything is inspectable with a simple command like `cat` or `diff`.

For example, when you move a card in your project, Threlmark just updates a single file, no special API call needed. It’s like a shared notebook that everyone can read and write to, without a middleman.

How the On-Disk Layout Sets the Rules and Keeps Everything Consistent

Threlmark’s layout is more than a folder structure; it’s a contract. At the root, you find a manifest (`threlmark.json`) and a dependency graph (`links.json`). Each project lives in its own folder, with a `project.json` for metadata, a `board.json` for lanes, and individual files for each card under `items/`.

This setup allows any tool—say, a script or a custom app—to read and write files directly, then trust that the data is current. The trick is that each file is atomic, so no partial updates can corrupt your data.

Making File-Based State Safe and Reliable

Using files as a database sounds risky, but Threlmark makes it safe with two key patterns. You can learn more about this approach in Disk Is the Contract: Inside Threlmark’s Local-First Architecture. First, atomic writes: every update writes to a temp file, then renames it, so crashes never leave corrupt data. Second, read-merge-write: updates read the current file, merge changes, and write back, preserving unknown fields for forward compatibility.

A real-world example? When a developer updates a card, only that card’s file gets touched. If another tool updates a different card simultaneously, both changes coexist without race conditions.

One File Per Item: Why It Prevents Race Conditions and Simplifies Sync

Instead of one giant JSON array, Threlmark uses one file per item. This prevents race conditions because each file can be updated independently. When a card moves lanes, only its specific file changes. The `board.json` then self-heals to match the current set of cards.

For example, imagine multiple team members editing different cards on their laptops. Because each file updates atomically, no one step overwrites another’s work.

How Threlmark’s Architecture Supports Offline-First, Speed, and Privacy

Threlmark’s local-first design means you can work anywhere—no internet needed. Sync happens in the background, so your data stays current across devices. It’s instant, private, and under your control.

Let’s say you’re on a plane, planning your next big project. You edit cards, prioritize tasks, and review dependencies—just like you would in a cloud app, but offline. When you reconnect, sync quietly updates everything, keeping your workflow smooth.

Making External Tools and AI Agents Play Nice with Files

Threlmark’s contract-based approach lets any external tool or AI agent participate by reading and writing files directly. For example, an AI assistant can suggest a new task, save it in the `suggestions/` folder, and watch for the `reports/` folder to confirm completion.

This open, permissionless model means you can plug in tools without complex APIs. They just follow the contract—reading, updating, and trusting the shared files.

The Power of a Portable, Inspectable, Restartable System

Because the entire system is just files, you can back it up, migrate it, or inspect it with simple commands. For more insights, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture. Want to move your setup to a new machine? Just copy the folder. Need to see what’s happening? Open a file. No database, no server, no lock-in.

This portability means your data is yours—always. It’s like having a digital notebook that’s always readable and ready to go.

Developer Simplicity: Why This Architecture Is a Developer’s Dream

Developers love this approach. No complex syncing layers or database schemas. Find out more in Disk Is the Contract: Inside Threlmark’s Local-First Architecture. Just read and write files. Handling conflicts? Merge patches. Moving to a new device? Copy the folder. It’s a straightforward, low-friction workflow.

For example, a team building a custom tool can extend Threlmark easily, just by reading and writing JSON files—no special SDKs or APIs needed.

Frequently Asked Questions

What does ‘disk is the contract’ really mean?

It means your local storage files are the authoritative record of your data, not a remote server. Changes happen directly on your disk, making everything transparent, portable, and offline-capable.

How does Threlmark handle conflicts when multiple devices update data?

It uses one file per item, so updates are atomic and independent. The system then reconciles the lane ordering and other metadata on each read, avoiding race conditions and data loss.

Can I use external tools or AI with this setup?

Absolutely. Since the data is just files, any tool that reads and writes JSON can participate—making automation, AI, and integrations straightforward without special APIs.

Is my data private and secure?

Yes. Because everything lives on your device, you control access. No need to trust a third-party server—your data stays local unless you choose to sync or share.

Do I still need a cloud or backend server?

Not necessarily. Threlmark’s design minimizes reliance on servers, using sync only for collaboration or backup. Your primary work environment is your local disk.

Conclusion

When the disk is the contract, your data becomes truly yours—easy to back up, move, and understand. Threlmark’s simple yet powerful architecture shows that a folder full of JSON files can handle complex workflows without a single server or database.

Imagine a future where your project data is always at your fingertips, fast, private, and fully under your control. That’s the promise of disk as the contract. Why settle for less?