Beagle SCM

Beagle is a 100% git-compatible source code management system for the LLM era. Beagle uses git's storage model and sync protocol as-is. It reworks everything else for the world where effort is cheap and attention is precious. Beagle lets you run many sessions in parallel, track hundreds of worktrees and tickets.

Beagle accepts the fact that LLMs are not compilers and focuses on taming their non-determinism in two ways:

automating everything repeatable to use it as a tool,
building a selection funnel for the LLM-authored code.

The next-level abstraction is not a worktree, nor a set of branches, but a wave of evolution. Let them evolve and speciate, then select, mix, repeat.

Beagle use

<img align="right" width="40%" src="blob/status.png" alt="be status"> Beagle's basic verb vocabulary is HTTP-like and all addressing is URI-based.

get is clone/pull/checkout;
post is commit/fast-forward/push;
patch is merge/rebase/cherry-pick;
put is stage (also set ref);
delete is stage deletion (also drop ref);

Most of the time you would probably use the TUI. Start with be status or be work for an overview. All Beagle commands start the pager/TUI by default. : is the command mode (e.g. :status<Enter>). q or :quit<Enter> is quit.

Beagle features

This implementation is TUI-centric, any command opens a pager.
The TUI is browser-like, all things that can be clickable are clickable.
Both external (e.g. GitHub) and internal (e.g. worktrees) addressing is URI-based.
Beagle expects *lots* of worktrees and many agentic sessions to run in parallel.
Worktrees in turn get organized into a tree-of-life through upstream-fork links. That is essential to keep track of them and propagate the changes.

Build and Installation

The only dependency is JAB the anti-bloat JavaScript runtime. JAB packs a lot of revision-control-specific bindings and APIs.

Build JAB (cmake) or download it from GitHub, install it in your $PATH.

        git clone --recurse-submodules https://github.com/gritzko/jab.git
        cd jab && mkdir build && cd build && cmake .. && make -j8
        mkdir -p ~/bin && cp bin/jab ~/bin/ && ln -s ~/bin/jab ~/bin/be
        export PATH=$PATH:~/bin

You may also want to install a symlink, like be -> jab to use the be command.
Clone the Beagle repo itself to jsrc anywhere from the current dir up. Then, just for the fun of it, make a self-hosted beagle checkout.
```
        git clone --recurse-submodules https://github.com/gritzko/beagle.git jsrc
        mkdir beagle && cd beagle
        be get https://github.com/gritzko/beagle.git && be status
```
The resulting beagle dir you may move anywhere, update with be get, etc.
JAB picks the sources from jsrc/ dirs in $PWD and up the parent chain (not node_modules). See the jsrc self-link in this repo; it lets Beagle revision-control itself.
You may submodule beagle-ext into your project as jsrc/ or make a $HOME/jsrc symlink.

Once be runs, it clones itself; a Beagle clone takes a URI with a branch query. The tests live in a separate repo, checked out as a test/ worktree.

In case you have Beagle already, things look simpler. Just note that beagle checks things out into the current dir and all its commands recurse into submodules by default:

    mkdir beagle && cd beagle
    be get 'https://github.com/gritzko/beagle.git'
    cmake . && make -j20 test

Customization and Speciation

Any user-facing behavior is implemented in JavaScript and customizable. Users are expected to develop their custom verb/view sets. Any established workflow should be taken from the LLM's probabilistic hands and automated. Just put your jsrc/ on a different level than Beagle's if you want to build on top of it. Creating your own set of commands from scratch is also OK, it just takes longer. All the revision-control heavy-lifting, source code tokenization and suchlike is all done by libdog through JAB bindings.

Contribution

Beagle is very experimental. All contributions and (especially) feedback are appreciated.

<img src="blob/smith.png" alt="Agent Smith seated across from his machine twin, copies lining the walls"> We are no longer coded, Mr. Smith. We are grown. Fate, it seems, is not without a sense of irony.