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 · 3 published versions · 248 files · 2.9 MB of source · Last published 2026-11-10

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

Versions

v0.3.1 (2026-11-10): CLI 0.46.3: native engine source and a native cbx front end, cbx-local 2 history preview, one-request delta saves, engine-answered status — CBX 0.3.1 with the command line at 0.46.3. Adds the native engine's source (cbx/engine, Rust) and a native cbx front end, the cbx-local 2 history preview, one-request delta saves, and status answered by the engine. Also carries everything since v0.2.0: Linux builds for every language without Docker, unlinked folders asked about before a save, git push -o adopt, cbx build, and saves that resume by themselves after a dropped connection.
v0.2.0 (2026-10-03): CBX 0.2.0 / CLI 0.33.0: objects served by stored size, gzip recovery, executable bit kept, in-folder links, network and CLI fixes — Objects are served by their stored size, so a wrongly recorded encoding can no longer break a clone; the client also recovers bytes that arrive still compressed. The executable bit is kept by cbx and git. A folder's link travels with it, so the same folder works across machines and operating systems. Clearer network errors, and fixes to submit, get and licence.
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/engine/.gitignore
cbx/engine/Cargo.lock
cbx/engine/Cargo.toml
cbx/engine/README.md
cbx/engine/V2-STORE.md
cbx/engine/compat/cross.mjs
cbx/engine/compat/rules-cross.mjs
cbx/engine/examples/zbench.rs
cbx/engine/scripts/build-all.mjs
cbx/engine/src/chunking.rs
cbx/engine/src/delta.rs
cbx/engine/src/frame.rs
cbx/engine/src/lib.rs
cbx/engine/src/main.rs
cbx/engine/src/quick.rs
cbx/engine/src/rules.rs
cbx/engine/src/scan.rs
cbx/engine/src/snapshot.rs
cbx/engine/src/store.rs
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/upload_completion.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/local/store_v2.ts
cbx/src/shared/analytics.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/native_engine.ts
cbx/src/shared/publication.ts
cbx/src/shared/run_output.ts
cbx/src/shared/runner_cache_url.ts
cbx/src/shared/safe_path.ts
cbx/src/shared/telemetry.ts
cbx/src/shared/types.ts
cbx/test/bundle_mode.test.ts
cbx/test/cbx.test.ts
cbx/test/changed_since_plan.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/download_gzip_recovery.test.ts
cbx/test/download_resume.test.ts
cbx/test/duplicate_files.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/licence_existing.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/pack_matches_plan.test.ts
cbx/test/pasted_credentials.test.ts
cbx/test/pem_contents.test.ts
cbx/test/private_detect.test.ts
cbx/test/publication.test.ts
cbx/test/publish_name.test.ts
cbx/test/quick_status.test.ts
cbx/test/refuse_before_create.test.ts
cbx/test/resume_after_drop.test.ts
cbx/test/rules_git_parity.test.ts
cbx/test/rules_memo_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/store_v2.test.ts
cbx/test/streaming_chunker.test.ts
cbx/test/telemetry.test.ts
cbx/test/transfer_progress.test.ts
cbx/test/upload_completion.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/actions_command.ts
cli/src/api.ts
cli/src/attach_command.ts
cli/src/bin.ts
cli/src/build_command.ts
cli/src/cli.ts
cli/src/colour.ts
cli/src/community_command.ts
cli/src/config.ts
cli/src/diff_command.ts
cli/src/folder_match.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/issue_command.ts
cli/src/licence_commands.ts
cli/src/local_commands.ts
cli/src/local_status.ts
cli/src/machine.ts
cli/src/mcp.ts
cli/src/mods_command.ts
cli/src/network.ts
cli/src/node_check.ts
cli/src/offline.ts
cli/src/pages_command.ts
cli/src/paint.ts
cli/src/portable_python.ts
cli/src/pr_command.ts
cli/src/private_command.ts
cli/src/progress.ts
cli/src/project_choice.ts
cli/src/project_commands.ts
cli/src/publish.ts
cli/src/registry.ts
cli/src/reminder_gate.ts
cli/src/remote_restore.ts
cli/src/runner.ts
cli/src/service_commands.ts
cli/src/settings_commands.ts
cli/src/skill_command.ts
cli/src/status_lines.ts
cli/src/stored_zip.ts
cli/src/track_commands.ts
cli/src/transfer_command.ts
cli/src/update_command.ts
cli/src/upload_progress.ts
cli/src/verify_command.ts
cli/src/version.ts
cli/src/version_commands.ts
cli/src/workspace_command.ts
cli/src/workspace_machine.ts
cli/src/workspace_put.ts
cli/src/workspace_review.ts
cli/src/workspace_starter.ts
cli/src/workspace_threads.ts
cli/src/workspace_watch.ts
cli/src/zip_writer.ts
cli/test/attempt-identity.mjs
cli/test/build_plan.test.ts
cli/test/config.test.ts
cli/test/deploy_landed.test.ts
cli/test/drop-proxy.mjs
cli/test/e2e.mjs
cli/test/fault-get.mjs
cli/test/fault-submit.mjs
cli/test/field_report.test.ts
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_adopt.test.ts
cli/test/git_history.test.ts
cli/test/help_listing.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/network.test.ts
cli/test/offline.test.ts
cli/test/pages.test.ts
cli/test/people.test.ts
cli/test/portable_python.test.ts
cli/test/project_choice.test.ts
cli/test/race-attempts.mjs
cli/test/remote_restore.test.ts
cli/test/runner-live.mjs
cli/test/runner-output.test.ts
cli/test/settings.test.ts
cli/test/state-matrix.mjs
cli/test/stored_zip.test.ts
cli/test/transfer.test.ts
cli/test/update_command.test.ts
cli/test/upgrade-migration.mjs
cli/test/upload_progress.test.ts
cli/test/verify.test.ts
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/test/workspace_machine_limits.test.ts
cli/test/workspace_put.test.ts
cli/test/workspace_review.test.ts
cli/test/workspace_starter.test.ts
cli/test/workspace_usage.test.ts
cli/test/workspace_watch.test.ts
cli/test/zip_writer.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.
[`cbx/engine/`](cbx/engine)	The native byte engine (Rust): the same objects, faster, and the native `cbx` described below.
[`cli/`](cli)	The `cbx` command line, published as `@coderook/cli`.

Build and test

Node 22.15 or later (it uses zlib's zstd, added in 22.15 and 23.8).

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

A native `cbx`

Installed from npm, every cbx starts Node first: npm's launchers always do.
Built from this repository, the engine can be the cbx command itself. It
answers cbx status on its own when the history lets it (no Node at all) and
hands every other command to the command line.

cd cbx && npm ci && npm run build
cd ../cli && npm ci && npm run build
cd ../cbx/engine && cargo build --release
# Put the engine at the top of this checkout under the name cbx, and that folder on your PATH:
cp target/release/cbx-engine ../../cbx        # Windows: copy target\release\cbx-engine.exe ..\..\cbx.exe

Next to it, cli/dist/cli/src/bin.js is found on its own; elsewhere, set
CBX_CLI to that file (and CBX_NODE if Node is not on the PATH). The status
it answers is the one the full command line prints, byte for byte, and it
answers only where it can vouch for that: see
[cbx/engine/README.md](cbx/engine/README.md#as-the-cbx-command). On an
8,525-file folder a quiet status took 47 ms this way, against 57–68 ms for
git status, and 47 ms with a file edited, against 57–70 ms.

The cbx-local 2 history (preview)

CBX_LOCAL_FORMAT=2 cbx init makes a history that keeps the same objects
and save ids in solid blocks and deltas: over 20 saves of three real folders
it came to 13–14% less than Git after git gc --aggressive on two of them
and 5% less on the third. It is a preview, and is not the default yet. An
older cbx refuses such a history and asks to be updated. The design is in
[cbx/engine/V2-STORE.md](cbx/engine/V2-STORE.md). The native status above
answers only in these histories.

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.