batty-251/cbx

Open-source version control for projects of any size: snapshots, content-defined chunking, real merges, offline first. Format and sync protocol specified. Apache 2.0. Mirror: github.com/AlexC1991/cbx

By Batty 251 (@batty-251) · Licence: Apache-2.0 · 1 published version · 155 files · 2.0 MB of source · Last published 2026-09-27

A public project on CodeRook. Browse it at https://coderook.com/batty-251/cbx.

Versions

v0.1.0 (2026-09-27): CBX 0.1.0: engine, local history, merges, CodeRook sync, format and protocol specs — First open-source release of CBX: the engine, a local history with lines and three-way merges, push and pull with CodeRook, and written specifications of the storage format and sync protocol. Apache License 2.0. Source mirror: https://github.com/AlexC1991/cbx

Files in the latest version

.gitignore
CONTRIBUTING.md
LICENSE
NOTICE
README.md
SECURITY.md
cbx/.gitignore
cbx/LICENSE
cbx/NOTICE
cbx/README.md
cbx/package-lock.json
cbx/package.json
cbx/spec/FORMAT.md
cbx/spec/PROTOCOL.md
cbx/src/core/cbx.ts
cbx/src/core/compress.ts
cbx/src/core/credentials.ts
cbx/src/core/detect.ts
cbx/src/core/download.ts
cbx/src/core/faults.ts
cbx/src/core/identify.ts
cbx/src/core/ignore_templates.ts
cbx/src/core/licence_texts.ts
cbx/src/core/licences.ts
cbx/src/core/profile.ts
cbx/src/core/publish_name.ts
cbx/src/core/retry.ts
cbx/src/core/rules.ts
cbx/src/core/secret_patterns.ts
cbx/src/core/solid.ts
cbx/src/core/staging.ts
cbx/src/core/tracks.ts
cbx/src/core/transfer_progress.ts
cbx/src/core/upload.ts
cbx/src/core/worktree.ts
cbx/src/local/errors.ts
cbx/src/local/history.ts
cbx/src/local/merge.ts
cbx/src/local/merge_text.ts
cbx/src/local/remote.ts
cbx/src/local/repository.ts
cbx/src/local/snapshot.ts
cbx/src/local/store.ts
cbx/src/shared/chunking.ts
cbx/src/shared/compression_policy.ts
cbx/src/shared/delta.ts
cbx/src/shared/format.ts
cbx/src/shared/merge_diff.ts
cbx/src/shared/publication.ts
cbx/src/shared/safe_path.ts
cbx/src/shared/telemetry.ts
cbx/src/shared/types.ts
cbx/test/cbx.test.ts
cbx/test/chunk_profiles.test.ts
cbx/test/chunked_send.test.ts
cbx/test/chunking.test.ts
cbx/test/compress.test.ts
cbx/test/credential_corpus.test.ts
cbx/test/credential_names.test.ts
cbx/test/deleted_carry.test.ts
cbx/test/detect.test.ts
cbx/test/download.test.ts
cbx/test/fetch_decision.test.ts
cbx/test/git_tracked.test.ts
cbx/test/keep_unchanged.test.ts
cbx/test/large_file_changes.test.ts
cbx/test/local_history.test.ts
cbx/test/local_merge.test.ts
cbx/test/local_remote.test.ts
cbx/test/merge_diff.test.ts
cbx/test/opposites.test.ts
cbx/test/pasted_credentials.test.ts
cbx/test/private_detect.test.ts
cbx/test/publication.test.ts
cbx/test/publish_name.test.ts
cbx/test/rules_git_parity.test.ts
cbx/test/safe_path.test.ts
cbx/test/scanner_edges.test.ts
cbx/test/spec_vectors.test.ts
cbx/test/staging.test.ts
cbx/test/starter_topup.test.ts
cbx/test/streaming_chunker.test.ts
cbx/test/telemetry.test.ts
cbx/test/transfer_progress.test.ts
cbx/test/upload_concerns.test.ts
cbx/test/upload_plan.test.ts
cbx/test/upload_retry.test.ts
cbx/tsconfig.json
cli/.claude-plugin/plugin.json
cli/LICENSE
cli/NOTICE
cli/README.md
cli/package-lock.json
cli/package.json
cli/scripts/copy-cbx-licence.mjs
cli/scripts/sync-plugin-version.mjs
cli/skills/coderook/SKILL.md
cli/src/api.ts
cli/src/attach_command.ts
cli/src/cli.ts
cli/src/config.ts
cli/src/diff_command.ts
cli/src/forge_url.ts
cli/src/git_history.ts
cli/src/git_remote.ts
cli/src/git_remote_bin.ts
cli/src/help.ts
cli/src/import_command.ts
cli/src/licence_commands.ts
cli/src/local_commands.ts
cli/src/mcp.ts
cli/src/offline.ts
cli/src/pages_command.ts
cli/src/progress.ts
cli/src/project_commands.ts
cli/src/publish.ts
cli/src/registry.ts
cli/src/runner.ts
cli/src/service_commands.ts
cli/src/skill_command.ts
cli/src/stored_zip.ts
cli/src/track_commands.ts
cli/src/transfer_command.ts
cli/src/version.ts
cli/src/version_commands.ts
cli/test/attempt-identity.mjs
cli/test/config.test.ts
cli/test/drop-proxy.mjs
cli/test/e2e.mjs
cli/test/fault-get.mjs
cli/test/fault-submit.mjs
cli/test/flag_parsing.test.ts
cli/test/get-protects-edits.mjs
cli/test/get-safety.mjs
cli/test/get-track.mjs
cli/test/git_history.test.ts
cli/test/import_command.test.ts
cli/test/links.mjs
cli/test/links_store.test.ts
cli/test/live.mjs
cli/test/local_history.test.ts
cli/test/offline.test.ts
cli/test/pages.test.ts
cli/test/race-attempts.mjs
cli/test/runner-live.mjs
cli/test/state-matrix.mjs
cli/test/stored_zip.test.ts
cli/test/transfer.test.ts
cli/test/upgrade-migration.mjs
cli/test/version-floor.mjs
cli/test/version.test.ts
cli/test/version_args.test.ts
cli/test/visibility.test.ts
cli/test/visitor_clone.test.ts
cli/tsconfig.json

README

CBX

CBX is version control for projects of any size: game projects, asset
libraries, datasets and model weights, as well as ordinary code. It keeps a
full history in your project folder and works entirely offline.
CodeRook is one place you can push that history, and
the protocol for doing so is published here too.

npm install -g @coderook/cli

cbx init
cbx save -m "First playable build"
cbx switch -c new-movement
cbx save -m "Try a double jump"
cbx switch main
cbx merge new-movement
cbx log

What it does

Every save is a whole snapshot. Files are split into content-defined pieces, so a piece repeated across saves or files is stored once. An edit in the middle of a 2 GB asset stores the pieces around the edit, not the file.
Compression where it pays. Every stored piece is compressed when that saves at least 2%, and checked against its SHA-256 every time it is read.
Small files are packed, so a project of tens of thousands of little files does not become tens of thousands of little files again.
Lines of work and real merges. A three-way merge takes whatever only one side changed, merges text files line by line, and marks only what is left. Binary files are never mangled: one side is kept and named.
It does not lose work. Restoring, switching, merging and pulling refuse to overwrite a change you have not saved, and never touch a file the history has never held.
Push and pull. cbx push sends each save to CodeRook as a save of its own; cbx pull brings saves back and merges when both sides moved on.

Commands


`cbx init`	Start a history in this folder (`.cbx/`)
`cbx save -m "…"`	Record the folder as it is
`cbx status`, `cbx diff`	What changed since the last save
`cbx log`	The saves on this line
`cbx switch [-c] <line>`	Move to another line, or start one
`cbx merge <line>`	Bring another line's work into this one
`cbx restore [paths] --from <save>`	Put files back the way a save had them
`cbx push`, `cbx pull`	Sync with CodeRook

cbx help <command> explains each one. The same binary also carries the
CodeRook account commands (submit, get, clone, projects, …); a folder
without a .cbx/ history behaves exactly as it always has.

Specifications

[spec/FORMAT.md](cbx/spec/FORMAT.md): everything in .cbx/, byte for byte, with test vectors. Another program can read and write the same histories and arrive at the same save ids.
[spec/PROTOCOL.md](cbx/spec/PROTOCOL.md): how a client pushes to and pulls from a CodeRook server.

The format's test vectors are read out of the document by
cbx/test/spec_vectors.test.ts and checked against the code, so the two
cannot drift apart unnoticed.

In this repository

Folder	What it is
[`cbx/`](cbx)	The engine: storage, chunking, the local history, merging, push and pull. Node's standard library only.
[`cli/`](cli)	The `cbx` command line, published as `@coderook/cli`.

Build and test

Node 20.11 or later.

cd cbx && npm ci && npm test
cd ../cli && npm ci && npm test

Licence

"CodeRook" is a name of ACCA Gaming Productions. The licence covers this code,
not the name, and not the CodeRook service.

CodeRook

Get started free

PUBLIC REPOSITORY

Opening batty-251/cbx…

Loading the public version history and verified file tree.