![](\"./assets/biscuit-and-crab.png\")
\n\n> A set of deterministic tools for a non-deterministic world\n\n## Package Areas\n\nThis monorepo is broken up into _package areas_ many of which combine a Library package for programmatic access and a CLI for terminal access.\n\n| Capability | Communicate | Inspect |\n| --- | --- | --- |\n| [biscuit-file](./biscuit-file/README.md) - _file utils_ | [biscuit-speaks](./biscuit-speaks/README.md) (TTS) | [tree-hugger](./tree-hugger/README.md) - _static-analysis_ |\n| [biscuit-hash](./biscuit-hash/README.md) - _hash utils_ | [messenger](./messenger/README.md) - _Discord, Slack, ..._ | [sniff](./sniff/README.md) - _host detection_ |\n| [biscuit-terminal](./biscuit-terminal/README.md) - _term detect & render_ | [playa](./playa/README.md) - _headless audio_ | |\n| [biscuit-visualized](./biscuit-visualized/README.md) - _data viz_ | | |\n| [schematic](./schematic/README.md) - _API clients_ | | |\n\nThen there are two libraries centered around the ideas of _composition_ and _orchestration_:\n\n- [darkmatter](./darkmatter/README.md) - provide a DSL on top of Markdown to provide powerful composition patterns in Markdown\n- [unchained-ai](./unchained-ai/README.md) - provides a compositional tool that allows the chaining and parallelization of many AI related tasks (both deterministic and non-deterministic).\n\nIt being 2026, it feels wrong not to have a more AI related package areas, and largely to meet your expectations we have added:\n\n- [agent-sandbox](./agent-sandbox/README.md) - FUTURE\n- [claudine](./claudine/README.md) - allows working cross-agent more consistent while offering some nice compositional strategies\n- [research](./research/README.md) - research and organize topics, publish as either an \"agent skill\", a \"deep dive doc\" or both.\n- [model-citizen](./model-citizen/README.md) - aids in the download, management, and serving of local LLM models\n\nEveryone 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:\n\n- [homelab](./homelab/README.md) - integrations with popular automation platforms and standards as well as some AV equipment for those with universal remotes.\n- [tabby](./tabby/README.md)\n- [queue](./queue/README.md) - a TUI for queuing work to start later\n\n> **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.\n\n## Usage\n\n- We have not yet pushed any of these packages to `crates.io` (though that is the eventual plan)\n- For many of the CLI's we also _plan_ on publishing to the **npm** package manager too\n- For now, however, if you want to use the libraries or CLI's in this monorepo you'll need to clone this monorepo:\n\n ```sh\n git clone https://github.com/yankeeinlondon/rusty-biscuit\n ```\n\nOnce you've cloned you're going to want to install the [`just`](https://github.com/casey/just) runner. This is used throughout this monorepo to organize all key devops operations. Install with:\n\n```sh\n# macOS\nbrew install just\n# ubuntu / debian\napt install just\n# windows\nwinget install Casey.Just\n```\n\n> **Windows:** recipes run through bash, so Cygwin or Git for Windows must be\n> on PATH before `just` can do anything. Run the PowerShell preflight, which\n> checks that (and tells you exactly what to fix) before delegating:\n> `powershell -ExecutionPolicy Bypass -File scripts\\init.ps1`\n\n\n\nasdf install just\n# Alpine\napk add just\n# Red Hat, CentOS, Rocky, etc.\ndnf install just\n# Arch, Manjaro, etc\npacman -S just\n# Snap package manager\nsnap install --edge --classic just\n# Nix Package manager\nnix-env -iA nixpkgs.just\n# Use NodeJS's **npm** package manager\nnpm install -g rust-just\n# Python's **uv** package manager\nuv tool install rust-just\n\n\nOnce installed run `just init` from the repo's root which will:\n\n- ensure you have all necessary build tools for your operating system\n- install some core CLIs from this monorepo to make sure all your `justfile` configurations will work with full fidelity\n\nThe [kache](https://github.com/kunobi-ninja/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`.\n\nSee [Development Environment Initialization](./docs/initialization.md) for the\ncomplete process, platform behavior, and troubleshooting guidance.\n\nAt this point you're ready to explore, install, test, whatever you like.\n\n- run `just` and it will give you all the \"recipes\" appropriate for the directory you are in\n- it will include things like:\n - testing\n - linting\n - installing\n - documentation drift\n - skill generation\n - _and more_\n\n## Shell Completions\n\nShell 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](./docs/shell-completions.md).\n\n## Local Development\n\n### Pre-push Hook\n\nA 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.\n\nReuse 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.\n\nRun `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.\n\nInstall the worktree-aware dispatcher into Git's shared hooks directory:\n\n```sh\njust init\n```\n\nLinked worktrees share one Git hooks directory. The installed dispatcher\nresolves the active worktree at push time, so each checkout runs its own\nversioned `.githooks/pre-push` protocol.\n\nThe hook's behavior is controlled by the `RUSTY_BISCUIT_PRE_PUSH` environment variable:\n\n| Value | Behavior |\n| --- | --- |\n| `scope-only` | Review constraints and publish scope; run no local gates |\n| `off` | Deprecated alias of `scope-only` |\n| `warn` | Publish complete passing or failing outcomes and allow the push |\n| `strict` | Publish complete outcomes, then block the push on failure (default) |\n\nFor example, to enable strict mode in your shell:\n\n```sh\nexport RUSTY_BISCUIT_PRE_PUSH=strict\n```\n\n`RUSTY_BISCUIT_PRE_PUSH_AREAS` (space-separated package names or area directories) replaces the computed scope with a fixed selection:\n\n```sh\nexport RUSTY_BISCUIT_PRE_PUSH_AREAS=\"claudine darkmatter\"\n```\n\n## License\n\nThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).\n\nYou are free to use, modify, and redistribute this software under the terms of that license. See the [`LICENSE`](./LICENSE) file for full details.\n\n> **Note:** If you run this software as a service, you must provide a link to the source code of the running version.\n"}