rusty-biscuit

Rusty Biscuit

A set of deterministic tools for a non-deterministic world

Package Areas

This monorepo is broken up into package areas many of which combine a Library package for programmatic access and a CLI for terminal access.

Then there are two libraries centered around the ideas of composition and orchestration:

• darkmatter - provide a DSL on top of Markdown to provide powerful composition patterns in Markdown
• unchained-ai - provides a compositional tool that allows the chaining and parallelization of many AI related tasks (both deterministic and non-deterministic).

It being 2026, it feels wrong not to have a more AI related package areas, and largely to meet your expectations we have added:

• agent-sandbox - FUTURE
• claudine - allows working cross-agent more consistent while offering some nice compositional strategies
• research - research and organize topics, publish as either an "agent skill", a "deep dive doc" or both.
• model-citizen - aids in the download, management, and serving of local LLM models

Everyone knows that naming is hard but no one talks about how grouping is equally as hard. Due to this we have decided not to name the category/group of the remaining packages:

• homelab - integrations with popular automation platforms and standards as well as some AV equipment for those with universal remotes.
• tabby
• queue - a TUI for queuing work to start later

Note: it was pointed out the convention would have had us use the other category name but then our well made point about naming and grouping being so hard would have fallen on deaf ears.

Usage

• We have not yet pushed any of these packages to crates.io (though that is the eventual plan)

• For many of the CLI's we also plan on publishing to the npm package manager too

• For now, however, if you want to use the libraries or CLI's in this monorepo you'll need to clone this monorepo:

  git clone https://github.com/yankeeinlondon/rusty-biscuit
  

Once you've cloned you're going to want to install the just runner. This is used throughout this monorepo to organize all key devops operations. Install with:

# macOS
brew install just
# ubuntu / debian
apt install just
# windows
winget install Casey.Just

Windows: recipes run through bash, so Cygwin or Git for Windows must be on PATH before just can do anything. Run the PowerShell preflight, which checks that (and tells you exactly what to fix) before delegating: powershell -ExecutionPolicy Bypass -File scripts\init.ps1

Once installed run just init from the repo's root which will:

• ensure you have all necessary build tools for your operating system
• install some core CLIs from this monorepo to make sure all your justfile configurations will work with full fidelity

The kache compiler cache is owned end to end by just init on hosts whose filesystem earns it — decided by a clone probe (APFS, btrfs/XFS-reflink, and ReFS qualify; ext4 and NTFS do not), never by the OS name: qualifying hosts get install, store placement, daemon, and activation (last); non-qualifying hosts are left alone with the reason named. just kache-status reports where this host stands and fails loudly on drift; the rulings are in docs/kache-strategy.md.

See Development Environment Initialization for the complete process, platform behavior, and troubleshooting guidance.

At this point you're ready to explore, install, test, whatever you like.

• run just and it will give you all the "recipes" appropriate for the directory you are in
• it will include things like:
  • testing
  • linting
  • installing
  • documentation drift
  • skill generation
  • and more

Shell Completions

Shell completions help people learn new CLI's as well as navigate a CLI they don't use that often. All of the CLI's in this monorepo have shell completions included for all the major shells (bash, zsh, fish). How to include the shell completions for each CLI is available as part of the CLI's help system but if you are using zsh or bash you can use my conditional script which will add shell completions for the CLI's in this monorepo (and just) which you have installed: Shell Completions.

Local Development

Pre-push Hook

A local pre-push hook runs just ci-local --l2: lint plus L1 and hostable non-focusing L2 for source-changed packages. It detects macOS, Linux, native Windows, or WSL2 with sniff. CI compiles unchanged direct reverse dependencies inside the changed package's Ubuntu check; they receive no separate jobs. For a clean outgoing HEAD, complete validation outcomes are published per package, environment, and tier. CI reuses only qualifying passing cells; failures remain diagnostic evidence and are rerun. A comparison containing only documentation changes gates no packages.

Reuse qualifying passes on every OS; required tests without qualifying passing evidence must run. Avoiding duplicate passing tests does not establish an OS-specific execution ban.

Run just ci-local --plan to preview execution, reused evidence, and persistent execution constraints before pushing. The hook reviews each pushed branch's committed plan against those constraints and passes the reviewed plan to clean local validation, which skips cells already covered by qualifying passing evidence. Scope is published independently of validation; incomplete runs and explicit package overrides provide no complete reusable validation evidence.

Install the worktree-aware dispatcher into Git's shared hooks directory:

just init

Linked worktrees share one Git hooks directory. The installed dispatcher resolves the active worktree at push time, so each checkout runs its own versioned .githooks/pre-push protocol.

The hook's behavior is controlled by the RUSTY_BISCUIT_PRE_PUSH environment variable:

For example, to enable strict mode in your shell:

export RUSTY_BISCUIT_PRE_PUSH=strict

RUSTY_BISCUIT_PRE_PUSH_AREAS (space-separated package names or area directories) replaces the computed scope with a fixed selection:

export RUSTY_BISCUIT_PRE_PUSH_AREAS="claudine darkmatter"

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).

You are free to use, modify, and redistribute this software under the terms of that license. See the LICENSE file for full details.

Note: If you run this software as a service, you must provide a link to the source code of the running version.