tcm-ts
tcm, the TypeScript codebase manager: Unison's codebase model (its ucm) for
plain TypeScript. Definitions are stored by the hash of their syntax tree, and names are only pointers to
hashes. So renames are free, nothing gets rebuilt,
and two versions of a dependency can live side by side. You don't need new syntax: any erasable TypeScript
file works as input, and Node runs the result directly through its built-in type stripping.
Requires Node ≥ 22.18 (tested on 24.15). Everything else comes with it, or is installed when your code first
needs it.
# tcm, as tcm's server runs it (binaries: tcm and tcm-ts)
curl -fsSLO https://tcm-server-production.up.railway.app/tcm-ts.tgz && npm install -g ./tcm-ts.tgz
mkdir demo && cd demo
tcm init # .tcm/codebase.sqlite, package.json "#codebase" imports, tsconfig, scratch.ts
tcm # watch: typecheck + hash scratch files, evaluate bare expressions
tcm add # save new definitions from scratch.ts
What's in it
What it does away with (dead code, circular imports, package.json, monorepo tooling, version skew, rebuilding and
retesting), each with where it stops and the test that proves it:
what tcm does away with.
- A content-addressed codebase. Scratch files are ordinary TypeScript.
tcm add/update store
definitions by hash; updates re-hash dependents automatically, and what stops typechecking goes to todo.
Getting started · hashing · CLI
- AI agents work in it.
tcm mcp gives coding agents (Claude Code, Cursor, …) tools and instructions for the
codebase's way of working: find, edit in a scratch file, update, fix what broke, test. tcm init sets it up.
Agents
- Editor integration. The codebase in a VS Code sidebar, pages for definitions and namespaces (rendered docs,
linked source, uses and used-by), one finder for names, docs and types, apps you can start, a table viewer;
in scratch files, each definition's status with Add/Update actions and watch values inline.
tcm lsp serves
it (also for Neovim and Helix). Editors
- Docs that can't go stale. JSDoc links, embeds and
```ts examples are resolved to hashes: they
follow renames and updates, examples are evaluated, and update reports the ones that break.
Docs
- Tests with Vitest, with nothing to set up. A test is a definition, cached by hash; it runs in Node, or in
Chrome when it renders a component. Results (and lint findings) travel with push and pull. Testing
- Linting and formatting with nothing to set up. oxlint, with plugins for what the code uses and findings
cached by hash; oxfmt, which never changes a hash, so stored code is always formatted. Both are configured by a
definition (
lint.config, fmt.config). Linting · formatting
- Search by type, as in Unison:
tcm find ':(xs: T[]) => T' finds matches up to renaming, reordered
arguments, async results, and more general or specific types. Search
- Real projects import as they are. neverthrow, ts-pattern and valibot import, verify and run.
Importing
- History by meaning, as Unison keeps it. History entries are hashed namespaces with parents, the same in
every codebase; diffs ignore renames and reformatting; merges go by history; undo anything.
History and merging
- Releases with versions and changelogs from the API. Any number of packages per codebase; each
release's version comes from semver checks of what changed in the package's API (in the manner of
cargo-semver-checks), and its notes list those changes, so the changelog writes itself.
Releases · publishing
- A forge in every server.
tcm serve has a web UI: the codebase's front page, its code by namespace and
definition, search by name, doc or type, history, and contributions reviewed along a review path (new code
before what uses it, re-hashed definitions folded), commented on and merged. Web UI
- Contributions. Propose a branch with
tcm contribute, review it as a diff of definitions (in the terminal
or in the web UI), comment, and merge it on the server. Contributions
- Sync and remote execution by hash. Push, pull and
run --on send only missing hashes, and received
code is re-verified, never trusted. Sync
- Browser apps with no network boundary to write. Placement is inferred from what code uses; server
functions are called by hash, so there's no client/server version skew. Apps ·
server API
- React server components with no directives. Async components and ones that read tables render on the
server; ones with state or handlers in the browser. No
"use client", no "use server". Pages render on the
server first and stream <Suspense> boundaries. React
- Typed tables that never silently disagree with your code, with typed migration chains, indexes,
atomic updates and transactions. Data
- Background jobs pinned to the code that enqueued them, plus cron schedules. Jobs
- Deploy and roll back by moving a name; old tabs keep working. Production
- Local-first PWAs and static sites. A
pwa beside the app makes it installable, opening offline and updating
itself; tcm build --static writes an app that needs no server as files for any static host.
PWAs
- Self-hosting: tcm-ts is developed in tcm: all of it is in its own codebase, served by tcm's server, and
this repository only says how to get it (
pnpm tcm). It verifies itself, and its tests run against its own
build. Browse its code ·
developing
New here? Read the introduction, then follow the tutorials:
your first codebase and your first web app. Or try the
examples: polls, a React notes app, a local-first PWA, and packages with their releases and changelogs.
To work on tcm itself: contributing.
All documentation: the docs site. Open items: limitations.
