README

tcmts.README · #3sdgbww6 · md file

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.codes/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
• Libraries without a registry. tcm lib add @alice.dev/geo mounts another codebase's release by its hash, read-only, checked as it arrives; tcm lib upgrade is one patch, its API's changes said first. Authors announce releases on the AT Protocol (tcm release --announce), and tcm hub runs a site that finds them all, checks each against its author's signature, and mirrors it. Libraries · hub
• 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.