Introducing tcm

Andrew Lisowski — Sat, 07 Nov 2026 00:00:00 GMT

tcm is a new way to store TypeScript. Instead of a folder of text files, your code lives in a codebase: a database of code. Each function, type and constant is stored on its own, under the hash of its code. Names are kept apart from the code, as labels that point at those hashes.

Writing code doesn't change. You write ordinary TypeScript in a scratch file, in the editor you already use. Once it typechecks, you add it to the codebase, which stores each definition in it. There's no new language: Node runs the stored code directly.

Keeping names apart from code makes everyday edits simpler. A rename moves a label, so no code is edited and nothing breaks. Changing a definition doesn't leave the code that uses it behind, either. tcm checks each place that uses it against the new version. The ones that still typecheck move to it, and the rest go on a todo list, with the reason.

Where it comes from

Most of the model is Unison's. Unison is a language built around storing code by its hash, and it showed what that makes possible: free renames, changes that carry through, scratch files that show values as you write, search by type, and history that knows a rename from an edit. tcm brings that model to TypeScript, and keeps the compiler, packages and editors people already use.

Sharing works as it does on Unison Share. Codebases are pushed and pulled by hash, and a contribution is a branch, reviewed as a diff of definitions rather than lines of text.

Your code as a graph

Each definition is stored with the hashes of what it uses, so a codebase is an exact graph of your code. A folder of files is a rough version of that graph: import one function from a file, and you depend on the whole file. With the exact graph, tcm knows what any change reaches, and much of what it does follows from that.

Tests run once. A test's result is kept with the hashes it reached. Only the tests a change reaches run again, and results travel with the code when you push and pull.
Apps ship only what they use. An app is bundled from what it reaches, so there's no dead code to remove.
Code runs where it belongs. Whether a definition runs on the server or in the browser is worked out from what it uses. Browser code calls a server function by importing it, with no routes or fetch calls. React server components work the same way, with no "use client" or "use server".
Deploys don't break open tabs. Calls from the browser to the server go by hash, and earlier builds stay served, so a tab keeps calling the code it loaded.

What goes away goes through each of these, and where it stops.

Try it

Install tcm and take the tutorial, or browse tcm's own code. tcm is developed in a codebase of its own, and its docs and this blog are pages in it.

Why Files

Andrew Lisowski — Sat, 07 Nov 2026 00:00:00 GMT

The core idea behind tcm is that there are no files: your code is stored in a database (called a codebase). But that raises the question: why do we store code in files at all?

Well, the answer is kind of obvious: that's just how computers work! But that's not the full story. Files are there because we put them there. Files help us define something, organize similar things into groups, and then group those further into folders. Seems necessary? Maybe not.

The downsides of files for code

So files and folders are (seemingly) good for organizing our code, but what baggage comes with them?

Placement comes with constraints - Putting a bit of code in a package seems simple, right? Not really. That package might only work on the server, so code the client needs can't go there. If you want that code on both the server and the client, you have to set up a third package to hold the shared code. You'll also have to make sure that package stays isomorphic, or else your bundle might blow up or your server might crash.
Files need managing - Is a value really used? We can try to rely on our tools, but cruft accumulates. Is the file too long? Too short? Too spread out? You need to decide ahead of time how much or how little should go where. That might make sense in the moment, but not as a project evolves.
Folders - And once you have files, which folder do you put them in? Oh, that changed? Now countless files have to change. Just like with files, we have to anticipate the ideal structure, then suffer later when it inevitably turns out to be slightly the wrong shape.

That's a whole lotta problems that aren't code! Files and folders are littered with hurdles that have nothing to do with shipping code, just with organizing it to appease the beast.

Knowledge bases

An interesting thing about knowledge bases is that the less organization, the better! Folders and organization are choices, and those choices mean constant maintenance and having to categorize things. If you free yourself from that, and instead keep a single flat folder of files that organizes itself through the connections between them, you start to do a lot less work.

Another concept found in knowledge bases is "evergreen notes". These notes are bite-sized concepts that you link together to form a web of thoughts and knowledge. With this, you don't repeat yourself much, but you have very detailed context embedded in the thoughts.

Could we apply these principles to code?

A graph of values

When you add code to your codebase, each value (types, constants, functions, classes) is stored as a row in a database. If you follow their imports, you get a big graph of how all the code in your program connects.

You can think of it just like a knowledge base. Instead of a directory of files with relative links to each other, it's a graph of bite-sized values.

Apps, packages and scripts become subsections of the graph, picked out into whatever output format we want. Need a package? It materializes with the things you need, and none of the things you don't. Because we work in values, we don't have to worry that an array lives in a server package: we just need the value.

Suddenly, all the problems of files are gone! (There are, of course, many new problems caused by this.) We didn't need to anticipate the needs of the future with how we structured our code's files. Instead, our code can transform to meet the demands of the moment.

Working on a feature? Pull all the relevant values into one file, or as many as you want. The code can meet your needs right there, no planning needed.

Files are human

Files are ultimately a tool for humans. Managing code the way tcm does, in a codebase, is a very different way of working. It's a bit easier to remember where a file is. After working in a codebase for a while, you get to know the lay of the land: you remember where that function is stored, like a mark on a map.

But that topology comes with constraints, and with our code as a graph, we can work around many of them.

tcm blog