# BrokeCrew 🤖⚡

[![CI](https://github.com/brokecrew/brokecrew/actions/workflows/ci.yml/badge.svg)](https://github.com/brokecrew/brokecrew/actions)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT)
[![Crates.io](https://img.shields.io/crates/v/brokecrew.svg)](https://crates.io/crates/brokecrew)

**A lightweight, resilient, async-first Rust CLI that coordinates a specialized team of AI personas backed by OpenRouter models.**

BrokeCrew makes free-tier models first-class citizens while eliminating their instability through live model catalog discovery, ranked multi-candidate fallback cascades, account-wide rate-limit budgeting, and multi-agent handoff pipelines.

---

## Why BrokeCrew (vs LiteLLM or RouteLLM)?

| Feature | BrokeCrew | LiteLLM Proxy / RouteLLM |
| :--- | :--- | :--- |
| **Footprint & Startup** | Single standalone native binary (~15MB), sub-10ms startup. | Heavy Python runtime, tens of pip dependencies, slower startup. |
| **Hardware Fit** | Designed to run smoothly on low-RAM ARM tablets, Raspberry Pis, and local dev boxes. | Heavy memory consumption unsuited for constrained devices. |
| **Persona Fallback Walk** | Declarative ranked candidates per persona (`qwen:free` → `deepseek:free` → paid fallback). | Static routing with complex configuration layers. |
| **Live Catalog Awareness** | Syncs `/v1/models` in background; skips dropped/offline models before wasting requests. | Often returns raw 404/400 errors when models vanish. |
| **Account-Wide Budgeting** | Tracks rolling 20 req/min and daily quotas (50 or 1,000 req/day) across all calls including router. | Typically only tracks proxy tokens, not OpenRouter account limits. |
| **Multi-Agent Handoffs** | Built-in typed pipelines (`coder` → `reviewer`) with real-time SSE streaming per persona. | Requires external orchestration frameworks (LangGraph, CrewAI). |

---

## Terminal Experience

BrokeCrew formats multi-agent discussions like a vibrant team group chat:

```text
$ brokecrew chat --pipeline build-and-review "Write a Rust LRU cache"

[coder] (qwen/qwen-2.5-coder-32b-instruct:free)
Here is a thread-safe, high-performance LRU cache implementation using std::collections::HashMap
and a doubly-linked list with generational indexing...

[reviewer] (meta-llama/llama-3.3-70b-instruct:free)
Code Review:
1. Concurrency: Eviction edge case when capacity is 0 is unhandled.
2. Memory Safety: Generational indices avoid raw pointers; good choice.
3. Suggestion: Implement std::borrow::Borrow to allow lookup by &str rather than String.
```

---

## Quickstart

### 1. Installation

```bash
cargo install brokecrew
```

Or build from source:
```bash
git clone https://github.com/brokecrew/brokecrew.git
cd brokecrew
cargo install --path .
```

### 2. Configure OpenRouter API Key

BrokeCrew securely stores your API key in your OS credential store (`keyring`), never in plaintext:

```bash
brokecrew config set-key
```

*(You can also export `OPENROUTER_API_KEY="sk-or-v1-..."` or pass `--api-key` for headless servers).*

### 3. Start Chatting

Zero-config instant routing:
```bash
brokecrew chat "build me a proxy checker site"
```
*Stage A regex/keyword routing automatically detects "build/site" and dispatches to the `coder` persona in 0ms!*

Run an interactive team session:
```bash
brokecrew chat
```

Run a multi-agent handoff pipeline:
```bash
brokecrew chat --pipeline build-and-review "Implement a token bucket rate limiter in Python"
```

Check model catalog and quota health:
```bash
brokecrew status
```

List available personas:
```bash
brokecrew personas list
```

---

## Declarative Personas (`personas.toml`)

Personas are defined in `~/.config/brokecrew/personas.toml` (or `./config/personas.example.toml`):

```toml
[[persona]]
name = "coder"
system_prompt = "You are a precise, terse coding assistant. Output working code, minimal commentary."
trigger_words = ["build", "code", "script", "function", "website", "api"]

[[persona.candidates]]
id = "qwen/qwen-2.5-coder-32b-instruct:free"
tier = "free"
is_stealth = false

[[persona.candidates]]
id = "deepseek/deepseek-coder:free"
tier = "free"
is_stealth = false

[[persona.candidates]]
id = "google/gemini-2.0-flash-001"
tier = "paid"
is_stealth = false
```

---

## License

Dual-licensed under either:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.