Development

Development

This is the developer guide for building blumi from source, running its tests, and navigating the codebase. blumi is a terminal-native AI coding agent built as a Rust workspace (with blugo, a Flutter phone app, alongside it and a React web UI embedded into the binary). This page covers the repository layout, the build/test/lint commands, continuous integration (CI), project conventions, and where each subsystem lives.

TL;DR / Key facts

• blumi is a Rust workspace: the crates live under crates/, with a per-crate map in the README.
• Build with cargo build — the web UI's dist/ is committed and embedded via rust-embed, so a plain build needs no JavaScript toolchain.
• Test and lint with cargo test --all-features, cargo clippy --all-targets --all-features -- -D warnings, and cargo fmt --all --check.
• The phone app, blugo, is a Flutter project in blugo/, outside the cargo workspace.
• The web UI is a React + Vite + TypeScript app in crates/blumi-web/frontend/.
• CI (.github/workflows/ci.yml) runs a Rust gate and a Flutter gate on every push to main and on PRs; it runs on Linux, so platform-gated code must be #[cfg]-guarded.
• Key crates: blumi-core (agent loop), blumi-tools / blumi-skills (tools), blumi-web (HTTP/SSE API), blumi-tui (terminal UI), and blumi (CLI + gateway + grid).

How is the blumi codebase structured?

The repository is a Rust workspace under crates/, with the Flutter phone app and the React web UI living alongside it.

crates/            the Rust workspace (see README for the per-crate map)
blugo/             the Flutter phone app (outside the cargo workspace)
crates/blumi-web/frontend/   the React + Vite + TS web UI
docs/screenshots/  images used by the README
.github/workflows/ci.yml     CI (Rust gate + Flutter gate)

How do I build and test blumi from source?

Build and test the Rust workspace with the standard cargo commands below; a plain cargo build needs no JavaScript toolchain because the web UI is pre-built and embedded.

cargo build
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all --check

The web UI's built dist/ is committed and embedded via rust-embed, so cargo build needs no JS toolchain. To work on the web UI:

cd crates/blumi-web/frontend && npm install && npm run build

The phone app:

cd blugo && flutter pub get && flutter analyze && flutter test

What does CI check?

Continuous integration runs a Rust gate and a Flutter gate; both must stay green to merge. .github/workflows/ci.yml runs on every push to main and on PRs:

• rust — cargo fmt --check, clippy --all-targets --all-features -D warnings, test --all-features (ubuntu, stable toolchain).
• flutter — flutter analyze + flutter test in blugo/ (Flutter 3.44.1).

Keep both green. Note CI runs on Linux, so platform-gated code (e.g. macOS-only launchd helpers) must be #[cfg]-guarded to avoid dead-code under -D warnings.

What are the contribution conventions?

Keep the per-change gate green and follow the commit and secrets rules below before merging.

• Per-change gate green before committing; Rust feature work merges to main via --no-ff.
• Commits authored by ankurCES; include the trailer Co-Authored-By: Blumi.
• Secrets (settings.json, keystores, key.properties) are gitignored — never commit them.

Where does each subsystem live?

Each major subsystem maps to a specific crate or path, listed below.

• Agent loop / session actor: crates/blumi-core.
• Tools: crates/blumi-tools (+ self-management tools in crates/blumi-skills).
• HTTP/SSE API: crates/blumi-web (handlers in src/api.rs, routes/state in src/lib.rs).
• Gateway command + service mgmt + grid: crates/blumi/src/{serve.rs,web.rs,grid/,discovery.rs}.
• TUI: crates/blumi-tui.

Frequently asked questions

What language is blumi written in?

blumi is written in Rust and organized as a cargo workspace, with crates under crates/. The companion phone app, blugo, is a separate Flutter project in blugo/, and the web UI is a React + Vite + TypeScript app in crates/blumi-web/frontend/.

Do I need Node.js or a JavaScript toolchain to build blumi?

No. The web UI's built dist/ is committed and embedded via rust-embed, so cargo build produces a working binary with no JS toolchain. You only need npm if you want to work on the web UI itself, via cd crates/blumi-web/frontend && npm install && npm run build.

How do I run the full check suite locally before pushing?

Run the same gates CI runs: cargo fmt --all --check, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features. For the phone app, run cd blugo && flutter pub get && flutter analyze && flutter test.

Why does my code break only in CI?

CI runs on Linux, so platform-gated code — for example macOS-only launchd helpers — must be #[cfg]-guarded. Otherwise it becomes dead code under clippy -D warnings and fails the Rust gate even though it compiled on your machine.

Where is the agent loop implemented?

The agent loop and session actor live in crates/blumi-core. Tools are in crates/blumi-tools (with self-management tools in crates/blumi-skills), the HTTP/SSE API is in crates/blumi-web, and the terminal UI is in crates/blumi-tui.