Imagine a project management tool that works entirely offline, without a cloud, and still plays nicely with any other tool. Threlmark’s secret? It treats your disk as the ultimate contract—your files are the database. No server, no lock-in, just plain JSON files that do everything.

This isn’t just a clever trick. It’s a fundamental shift in how you think about data, flow, and automation. In this article, you’ll see how Threlmark’s local-first, file-based approach makes your workflow more reliable, portable, and open—and how it powers AI agents to do the heavy lifting without missing a beat.

Key Takeaways

• Treat your disk as the definitive source of truth—use plain JSON files for maximum transparency.
• Atomic file writes prevent data corruption, ensuring safety during crashes or interruptions.
• Design your system to be restartable—avoid in-memory state that can be lost.
• External tools and AI agents can seamlessly participate by just reading and writing files.
• Backups and migrations become trivial—just copy folders or sync them with any tool.

Why Using Files Over a Database Creates a Smarter System

Choosing files instead of a traditional database might sound risky—until you see the benefits. Threlmark’s architecture relies on simple JSON files stored right on your disk. This makes the data portable, easy to inspect, and free from server lock-in.

For example, you can back up your entire system with a simple copy or sync. Want to migrate to a new machine? Just copy the folder. It’s like having a physical book of your data—transparent, accessible, and straightforward.

This approach fits perfectly with local-first design, where the system prioritizes working offline and seamlessly syncing changes across devices.

How JSON Files Become Your Single Source of Truth

In Threlmark, every project, card, and dependency lives as a JSON file. The `threlmark.json` at the root acts as the manifest—like the table of contents for your entire setup—while each card gets its own file in the `items/` folder.

This means your data is just a series of plain text files, easy to read and edit. Want to see what’s next? Just open a file. Need to tweak a card? Edit the JSON, save, and it’s updated everywhere.

This simplicity makes the system incredibly flexible. External tools or scripts can join the party just by reading or writing files. No APIs, no special protocols—just plain JSON.

Local-First Design: Why It Powers Reliability and Portability

Local-first means your data lives on your device, not in the cloud. Threlmark’s design ensures you can work anywhere, even offline. When you reconnect, syncing is just copying files—no conflicts, no data loss.

Think of it like having a notebook that you can carry around, add notes to, and then sync with your other notebooks effortlessly. If your laptop crashes? Just restore from your backup—your data is safe, complete, and ready to go.

This approach also simplifies backups. You don’t need complex database dumps. Just copy your folder, and your entire system is preserved.

Dealing with Risks and Challenges of File-Based Data

Storing everything in files isn’t without its risks. Concurrency, schema drift, and conflict resolution are real challenges. Threlmark addresses this with atomic writes and tolerant normalization.

Atomic writes mean updates happen in one go—write a temp file, then rename it. That way, crashes never corrupt your data. Tolerant normalization lets older tools read newer files without breaking—unknown fields are preserved, and defaults fill in the gaps.

For example, if two agents update the same card simultaneously, the system gracefully merges changes without clobbering each other. It’s like editing a shared document with your partner—no conflicts, just smooth collaboration.

How External Tools and AI Agents Play Nicely With Files

Threlmark’s design makes it easy for outside tools to participate—no API needed. As long as they can read and write files, they can join the workflow.

Take AI agents. They can analyze, suggest, and even close their own loop by updating JSON files directly. For instance, an AI can mark a card as ‘Done’ by editing its file—no middleman, no API calls, just file manipulation.

This openness accelerates automation and collaboration. External scripts, IDE plugins, or AI assistants can all work together seamlessly, thanks to a common, transparent data format.

What It Means for Your Workflow and Data Safety

With Threlmark’s approach, your data is always inspectable and portable. Backups are a matter of copying a folder. Restoring is just copying back. No vendor lock-in, no proprietary formats.

In practice, this means less downtime, fewer surprises, and more control. You can run your system on a USB stick or a Raspberry Pi—perfect for sensitive projects or environments with limited internet.

And because every change is just a file write, debugging becomes simpler. Want to see what changed? Just run a diff. Need to troubleshoot? Open the files directly.

Key Takeaways: How To Use Threlmark’s File-Based Approach Today

• Keep your data in plain JSON files for maximum transparency and compatibility.
• Use atomic write patterns to prevent corruption during updates.
• Leverage the folder structure for easy backups, restores, and external integrations.
• Design your system to be restartable: no in-memory state, only files.
• Enable agents and tools to participate by reading and writing files directly.

Frequently Asked Questions

What does “disk is the contract” really mean?

It means your data lives directly in files on your disk, and those files define the system’s state. The file layout becomes the ultimate interface, making everything transparent, portable, and easy to manage.

Why choose JSON files instead of a database?

JSON files are simple, human-readable, and portable. They avoid lock-in, enable easy backups, and allow external tools or agents to participate without complex APIs or dependencies.

How does Threlmark handle conflicts or concurrent edits?

It uses atomic writes and tolerant normalization—merging changes gracefully and preventing corruption. This way, multiple agents can update files without clobbering each other.

Can external tools or AI agents modify my data safely?

Yes. As long as they can read and write files, they integrate seamlessly. Threlmark’s file structure supports direct editing, automation, and even self-updating AI workflows.

What happens during schema changes or updates?

Threlmark preserves unknown fields and uses defaults for missing data, so schema evolution is forward-compatible. Older tools can still read newer files without breaking.

Conclusion

Threlmark’s approach proves that simplicity can be revolutionary. By making the disk the contract, it transforms your workflow into a transparent, reliable, and open system—ready for automation and collaboration.

Next time you think about data management, ask yourself: could my system run entirely from files? Sometimes, the simplest solution is the strongest—because it’s just plain, honest, and right there on your disk.