Imagine a project management tool that doesn’t rely on a cloud or a central server. Instead, it lives entirely on your disk. That’s the core idea behind Threlmark’s “disk is the contract” approach. It’s a bold move that turns conventional wisdom on its head.

Why does this matter? Because it makes your project data portable, safe from server crashes, and open to any tool that can read files. If you’re tired of vendor lock-in and databases that lock your data away, this article shows you how Threlmark’s design delivers.

Key Takeaways

• Using disk files as the project’s API makes data portable, inspectable, and safe from crashes.
• Atomic write patterns prevent corruption, ensuring data integrity even during unexpected failures.
• One file per item avoids race conditions and simplifies external tool integration.
• Self-healing boards keep project views accurate without manual cleanup.
• External tools and AI can participate naturally by reading and writing JSON files directly.

What does ‘disk is the contract’ really mean?

“Disk is the contract” means your project data isn’t stored in a database or a cloud. Instead, it lives in simple JSON files on your disk. The files are the system’s truth, the way it communicates, and the way it integrates with other tools.

Picture a folder full of JSON files. Each card, project, or link is a separate file. When you update a file, you change the system. When you want to see the state, you read the files. No middleman, no API, just files.

This approach makes your data transparent. You can peek into any file, see exactly what’s stored, and even modify it with your favorite editor. Plus, backing up or migrating your data is as simple as copying files.

How the file layout turns disk into a living project hub

Threlmark’s file structure isn’t just a random collection. It’s a carefully designed contract that guides data storage. At the root, you find files like threlmark.json (the manifest) and links.json (the dependency graph).

Each project gets its own folder with project.json (metadata), board.json (lane order), and items/ (cards). External suggestions sit in suggestions/, and recorded handoffs in handoffs/. All these files are regular JSON, easily inspected and changed.

Shared items, archived projects, and report zones are also just files. This consistency makes the entire system transparent and portable — you can back it up, move it, or modify it without breaking anything.

Why turning disk into the API simplifies and powers your work

Using files as the API means no need for a database or a server. Any tool — a script, an editor, or an external app — can read and write these JSON files directly. This openness enables seamless integrations and automation.

For example, an AI agent can read a card’s JSON, decide it’s ready, and move it to “Done” by just editing a file. No API calls, no complex syncing. Just file operations.

It also means your data is safe from crashes. An atomic write ensures no corruption — if your system crashes during a save, you’re still left with a complete, valid file. It’s a simple yet powerful safeguard.

Making file-based state safe and reliable

Two patterns keep this system trustworthy: atomic writes and tolerant merging. Atomic writes involve writing to a temporary file, then renaming it — a guaranteed way to prevent corruption during crashes.

Read-merge-write means updates read the current file, merge changes carefully (preserving IDs and timestamps), and write atomically. This approach allows multiple tools to update files without clobbering each other.

For example, a script that updates a card’s status won’t accidentally delete other data because it merges changes rather than overwriting everything. This makes the system resilient and friendly for automation.

How a self-healing board keeps your project view accurate

Threlmark’s board isn’t just a static list. It’s a self-healing structure that reconciles itself each time you read it. It compares the list of items in items/ with the lane order in board.json and fixes discrepancies automatically.

Suppose an item gets deleted or moved outside the lane; the next read will reconcile the board, removing or placing it correctly. This keeps your project view consistent without manual cleanup.

This approach saves time and prevents errors, especially in multi-tool environments where files might get out of sync.

How Threlmark enables external tools and AI to join the system

Because everything is files, external tools can participate without special permissions or APIs. They just need to read, modify, and write JSON files in the right folders.

For instance, IdeaClyst or other AI agents can scan the suggestions/ folder, pick up new ideas, and then update the cards directly by editing the files. When they mark a task as done, they’re just changing a JSON file.

This openness makes automation natural and flexible, reducing vendor lock-in and unlocking a vibrant ecosystem of tools.

Real-world example: How a developer uses Threlmark to track multi-projects

Imagine a developer juggling three projects: a website, a mobile app, and a backend API. Each has its own folder with cards, lanes, and dependencies. They check progress by opening JSON files directly or using scripts that read the files.

When a bug is fixed in the backend, the developer updates the corresponding card in items/. An automation script then moves that card to “Completed” based on a change in the JSON.

All of this happens without a central database — just files, hooks, and scripts. The system remains lightweight, transparent, and adaptable.

Frequently Asked Questions

Is using files instead of a database slower or less scalable?

Not necessarily. For many project management tasks, file-based systems are fast enough, especially with proper atomic writes and caching. Threlmark is designed for local-first workflows where scale isn’t measured in millions of records.

How does Threlmark handle concurrent updates?

It uses atomic file writes and read-merge patterns to prevent conflicts. Since each item gets its own file, multiple tools can edit different cards simultaneously without clobbering each other.

Can I integrate Threlmark with other tools?

Absolutely. Because everything is just files, any tool that can read/write JSON can participate. This openness encourages automation, scripting, and custom integrations without vendor lock-in. Check out the project on GitHub for more.

What about data backup and migration?

Backing up Threlmark is as simple as copying the entire data directory. Migration is just moving files. No complicated export/import processes — just files and folders.

Is this approach suitable for large teams or enterprise?

While ideal for local, small, and medium-sized workflows, larger teams might need additional synchronization tools. But for those who value transparency and control, this model scales well within its scope.

Conclusion

Threlmark’s approach of making disk the contract turns project management into a simple, resilient, and open process. It strips away layers of complexity and vendor lock-in, leaving you with a transparent system that’s easy to extend and trust.

Next time you think about data storage, ask yourself: could the disk really be the contract? If so, you’re holding the key to smarter, safer, and more flexible projects.