Everything your reef needs.
From install to autonomous care. Full documentation is in the GitHub repo. This page has the quick reference.
Install
Clone and bootstrap
$ cd ~/.bluei && ./scripts/bootstrap.sh
Bootstraps the Python environment, verifies core tools, creates workspace directories.
Interactive setup
First-run wizard walks you through configuration. Then register your first repo with bluei onboard --repo /path/to/project.
CLI Commands
19 commands covering the full repository health lifecycle. Most run once and forget.
Interactive first-run setup wizard.
Headless onboarding for a new repository.
Run discovery scan for issues across all detectors.
Dry-run preview. Shows specks without creating anything.
Fix issues and open pull requests.
Show vitality score (0–100) and trend.
Show agent or repo status.
Generate HTML or PDF QA report.
Scan for hardcoded secrets and API keys.
Run operational checks and diagnostics.
Manage learned fix patterns. List, show, deactivate, reactivate.
Plan and execute multi-finding refactor campaigns.
Propose, shadow-test, and activate learned detector rules.
Generate a static observability dashboard.
Generate a GitHub Actions CI workflow.
Schedule recurring runs via host cron.
Detectors
8 language categories covered by 7 built-in tools plus optional LLM backends. Missing tools are skipped gracefully.
Lint errors, style issues, security bugs, comprehension misuse.
Code quality, style violations, complexity analysis.
Type safety: missing types, explicit any, untyped imports.
Bugs, style issues, dead code, simplification opportunities.
Quoting issues, deprecated syntax, injection vectors.
Unversioned images, apt cleanup, layer consolidation.
Header spacing, bare URLs, hard tabs, line length.
Secrets: AWS keys, GitHub tokens, API keys, private keys, high-entropy strings.
Care Levels
Graduated autonomy model. Start in observe. When you trust the fixes, move up. Nothing happens by surprise.
Scan only. Reports what it finds. No issues, no PRs, no code changes. Pure visibility.
Creates GitHub issues from findings. Categorized, labeled, linked to source. No code changes.
Opens fix pull requests. Grouped by category. You review and merge. The routine was handled.
Fixes and merges. For repos you trust bluei with. High-confidence fixes only. Full audit trail.
Architecture
Standalone-first design. No platform dependency. The deterministic cascade tries 8 stages before falling back to LLM — saving ~65% of LLM calls.
host cron / CLI
↓
bin/bluei — bash wrapper
↓
RunEngine — orchestrated QA cycle
↓
sandbox_local_runner — execution engine
↓
repo worktrees · GitHub API · vitality snapshots
Fix Cascade
8 deterministic stages tried in order before LLM fallback. Faster, cheaper, and more reliable than pure AI fixes.
1. ruff --fix · 2. ruff format · 3. pyupgrade · 4. autoflake
5. isort · 6. recipe engine · 7. pattern replay · 8. AST transforms
↳ LLM fallback (claude / opencode)
Full Documentation
For the complete reference — campaigns, emergent rules, plugin system, config reference, deployment — see the GitHub repo.
View on GitHub