Maabarium

Local-first autonomous research and evaluation workflows in Rust.

Council-driven proposals • Git-isolated experiments • SQLite persistence • Tauri desktop console

Maabarium is a Rust workspace for running blueprint-driven improvement loops across code, prompts, product work, and research.

The project is inspired by Andrej Karpathy's Autoresearch pattern and adapts that keep-winner loop into a Rust-first, local-first workflow engine.

The name comes from Swahili “maabara” = laboratory - the ultimate personal optimization workshop.

At a high level, each run follows the same keep-winner pattern:

1. load a blueprint
2. generate a proposal through configured models
3. apply the proposal in an isolated git-backed workspace
4. evaluate the result in a sandbox or domain-specific evaluator
5. keep, reject, or export the outcome with persistence and traces

Git is a required runtime dependency for the isolated worktree flow. The desktop app, CLI run command, and macOS install script now detect when Git is missing, inform the user, and attempt to install it automatically through a supported system installer.

What ships today:

• council-driven proposal generation with configurable model routing and request pacing
• git-backed experiment isolation, proposal application, and winner promotion
• SQLite persistence for experiments, metrics, proposals, and desktop history views
• keychain-backed provider secret storage
• research and LoRA-oriented evaluator flows alongside general code and prompt workflows
• explicit blueprint evaluator overrides via evaluator.kind = "builtin" | "process", with built-in subtype selection for code, prompt, research, and lora
• a Tauri desktop console with setup persistence, blueprint library management, live run state, history, diff, and logs

See docs/BLUEPRINT_SPEC.md for the full blueprint contract, including explicit built-in evaluator selection and template-aware evaluator routing.

Workspace

• crates/maabarium-core — engine, evaluators, git manager, persistence, export
• crates/maabarium-cli — command-line interface for running, inspecting, and exporting experiments
• crates/maabarium-desktop — Tauri desktop console with the web UI and native shell

Current Status

The repository has a working core runtime, CLI, and Tauri desktop application.

Current repository capabilities include:

• council-driven keep-winner engine orchestration
• blueprint-driven model assignment with explicit and round_robin strategies
• Wasmtime-backed sandbox policy validation and subprocess-based evaluation paths
• desktop onboarding/setup persistence for runtime strategy, local and remote providers, workspace defaults, and research search mode
• desktop packaging and updater support for the Tauri app shell

Desktop Packaging

The desktop application is the Tauri project in crates/maabarium-desktop, shipped as Maabarium Console.

Current supported packaging/distribution path:

cd crates/maabarium-desktop && pnpm tauri build

Current hosted desktop releases support Apple Silicon Macs running macOS 11 or later.

Expected macOS bundle output:

target/release/bundle/macos

Desktop runtime data is external to the app bundle and stored in app-specific OS locations.

On macOS, the desktop app uses:

• ~/Library/Application Support/com.maabarium.console/maabarium.db
• ~/Library/Logs/com.maabarium.console/maabarium.log
• ~/Library/Application Support/com.maabarium.console/blueprints/
• ~/Library/Application Support/com.maabarium.console/bin/maabarium

Release builds do not migrate repository-local desktop runtime files by default. Debug builds keep that migration path for local development, and release smoke builds can opt back in with MAABARIUM_ENABLE_LEGACY_DESKTOP_MIGRATION=1.

The desktop bundle also seeds bundled blueprint TOMLs into the app-data blueprint library, and release bundles can ship a standalone CLI resource for desktop installs.

On supported desktop builds, the first-run setup flow can also:

• install Git automatically when it is missing
• install or remove a managed shell link at ~/.local/bin/maabarium for the bundled CLI
• detect when ~/.local/bin is missing from PATH and show shell-specific guidance
• install Ollama, start Ollama, and pull any missing recommended local models through an explicit in-app action

Release desktop builds should provide MAABARIUM_UPDATE_PUBKEY or MAABARIUM_UPDATE_PUBKEY_FILE plus MAABARIUM_UPDATE_BASE_URL or MAABARIUM_UPDATE_MANIFEST_URL during pnpm tauri build so packaged installs embed the updater trust anchor and manifest endpoint.

The published desktop updater channels are stable and beta. Stable releases continue to publish the installer-facing root latest.json, and the in-app updater reads stable/latest.json or beta/latest.json.

See docs/DESKTOP_PACKAGING.md for the fuller packaging and updater flow.

Quick Start

Build The Workspace

cargo build

Build An Optimized Local Binary

Portable optimized build with whole-program optimization:

cargo build --profile release-lto

Opt-in local-machine tuning for Apple Silicon or any other fixed developer host:

RUSTFLAGS="-C target-cpu=native" cargo build --profile release-lto

Use the native-tuned command only for local benchmarking or personal builds. Distributed artifacts should keep the portable build profile so they remain compatible across machines in the same target family.

Run The CLI With The Example Blueprint

cargo run -p maabarium-cli -- run blueprints/example.toml --db data/maabarium.db

Inspect Recent Experiment History

cargo run -p maabarium-cli -- status --db data/maabarium.db

Export Experiment History

cargo run -p maabarium-cli -- export --db data/maabarium.db --format json --output exports/history.json
cargo run -p maabarium-cli -- export --db data/maabarium.db --format csv --output exports/history.csv

Manage Provider API Keys Through The OS Keychain

cargo run -p maabarium-cli -- keys set openai
cargo run -p maabarium-cli -- keys get openai
cargo run -p maabarium-cli -- keys delete openai

Launch The Desktop App In Development

cd crates/maabarium-desktop
pnpm install
pnpm tauri dev

Choosing A Workflow Type

• Use code-quality when you want to improve existing source files and validate the result against tests or runtime behavior.
• Use product-builder when the workflow should change an application across multiple source trees, not when you only want one named markdown output.
• Use general-research when the deliverable is a sourced brief with citations and markdown-style output.
• Use prompt-improvement when the workflow should create or refine prompt or document assets; prefer an exact .md target path when you want one specifically named file.

In the desktop Blueprint Wizard, the guided flow now works in this order:

1. set the workflow name
2. choose the goal and workflow family
3. refine the description after the goal-derived defaults are in place
4. confirm the output shape
5. verify workspace and runtime details
6. review before save

Choosing a goal updates the derived workflow defaults but does not auto-advance the wizard. Custom description text is preserved when you switch goals, and you can use the explicit Next Step action when you are ready to move on. Advanced controls still expose the raw template, metric, agent, and model tabs when you need lower-level editing.

When the workflow should create or refine one named document, use an exact relative target path such as docs/project-brief.md instead of a broad glob. Use globs like src/**/*.rs or docs/**/*.md when the workflow is meant to operate over a family of existing files.

Blueprint Gallery

• blueprints/example.toml — example prompt-lab workflow for improving Maabarium itself
• blueprints/code-quality.toml — correctness, readability, maintainability, and performance improvements for production codebases
• blueprints/prompt-improvement.toml — prompt clarity, specificity, and usability improvements for reusable prompt assets
• blueprints/product-builder.toml — end-to-end product strategy, implementation, and verification loop for whole applications
• blueprints/general-research.toml — grounded research workflow with source tracking and explicit citations
• blueprints/lora-adapter.toml — sandboxed validation of externally produced LoRA adapter artifacts and reproducibility metadata

Documentation

• docs/BLUEPRINT_SPEC.md
• docs/ARCHITECTURE.md
• docs/BUILD_PROFILES.md
• docs/DESKTOP_PACKAGING.md
• docs/ROADMAP.md
• CONTRIBUTING.md
• SECURITY.md

Contributors

If you want to contribute to Maabarium, start with CONTRIBUTING.md. It covers repository scope, validation commands, documentation expectations, and the review standards contributors should follow.

For product direction and future capability ideas, see docs/ROADMAP.md.

Validation

Targeted validation commands used in this repository:

cargo build
cargo test
cargo test -p maabarium-core --test engine_loop
cd crates/maabarium-desktop && pnpm build

License

Maabarium is licensed under the Apache License 2.0. See LICENSE.