A multi-agent LLM orchestration platform built with Elixir and Phoenix LiveView. Spawn AI agents, wire them together, run structured games and debates, and watch them interact in real-time with streaming responses and cost tracking.
- Agent Grid: Spawn up to 12 concurrent agents, each with independent model, personality, and temperature
- Real-time Streaming: Token-by-token response rendering via SSE with 50ms batched UI updates
- Agent Wiring: SVG cable visualization connecting agents with topology-based message routing (broadcast, chain, ring, star)
- 78 Personality Presets: Historical figures, fictional characters, professionals, personality types, and fun personas across 5 categories
- 11 Meta Presets: Structured multi-agent interaction patterns with game boards, scoring, and tools
- 30 Agent Tools: Web search (Brave), memory, calculator, dice, randomness, timers, buzzers, scoring, voting, whisper, word tracking, rhyme checking, forbidden words, codenames board, tic-tac-toe board
- Cost Tracking: Real-time LLM cost display with per-model pricing, sparkline graphs, and per-agent breakdowns
- Fleet Configuration: Group agents, apply shared prompts, coordinate broadcast responses
-
Shuffle Controls: Randomize presets, models, or temperatures fleet-wide with category filters (
$, $ $, provider) - 22 LLM Models: Groq (gpt-oss, llama, compound, qwen, llama-4), 9 Anthropic Claude models, and 4 Google Gemini models (2.5 Pro, 2.5 Flash, 2.0 Flash, 2.0 Flash Lite)
- CLI Games: Run debates, telephone, and trivia directly from the terminal
# Install dependencies
just setup # or: make setup
# Create .env file (see env.example for all options)
echo "GROQ_API_KEY=your_key_here" > .env
# Start the server
just server # or: make serverVisit localhost:4000 for the dashboard, or localhost:4000/meta for meta preset sessions.
4 agents spawn on startup by default (configurable via LILBOTS_AGENT_COUNT) using openai/gpt-oss-20b. All agents receive dynamic date context in system prompts. A health check is available at /health.
Structured multi-agent interaction patterns with game-specific tools and visual boards:
| Pattern | Agents | Description |
|---|---|---|
| Debate | 4 | Pro vs Con with moderator and adjudicator |
| Panel Discussion | 4-6 | Moderated multi-perspective discussion |
| Brainstorm | 3-5 | Structured ideation with critic and synthesizer |
| Writers Room | 3-5 | Collaborative creative writing |
| Trivia | 3-6 | Quiz show with buzzer and scoring tools |
| Rhyme Battle | 3-5 | Poetry competition with rhyme-checking judge |
| Word Chain | 3-8 | Sequential word association game |
| Telephone | 3-10 | Message transformation chain (standard, lossy, creative) |
| Tic-Tac-Toe | 2 | Classic game with visual SVG board |
| Taboo | 3-4 | Word guessing with forbidden word enforcement |
| Codenames | 4 | Team-based word association with visual board |
| Tool | Description |
|---|---|
web_search |
Search the web via Brave Search API |
memory_save / memory_recall |
Persistent key-value memory per agent |
calculator |
Safe mathematical expression evaluation |
dice / coin_flip / pick_random / shuffle / draw |
Randomness tools (d20, 2d6+3, etc.) |
timer_start / timer_check |
Countdown timers for timed challenges |
buzzer |
Buzz in for trivia/quiz games |
add_score / get_score / leaderboard |
Scoring and rankings |
rhyme_check |
Verify rhyming word pairs |
track_word / list_used_words |
Word usage tracking for word games |
set_forbidden / check_forbidden |
Forbidden word enforcement for Taboo |
whisper |
Private messages between specific roles |
create_poll / cast_vote / poll_results |
Multi-agent voting |
codenames_generate / codenames_reveal / codenames_view |
Codenames board management |
tictactoe_generate / tictactoe_move / tictactoe_view |
Tic-Tac-Toe board management |
Browser ──WebSocket──▶ Phoenix LiveView
│
PubSub Topics
├─ "agents" (lifecycle, status, responses)
├─ "agent:<id>" (streaming tokens)
└─ "costs" (cost tracking updates)
│
┌────────────┼────────────┐
▼ ▼ ▼
AgentSupervisor CostTracker MetaPreset
(DynamicSupervisor) (ETS) Engine
│ │
┌─────┼─────┐ Topology Router
▼ ▼ ▼ (broadcast/chain/
Agent Agent Agent ring/star/tree)
(GenServer, each)
│
TaskSupervisor
(async LLM calls)
│
LLM Module
(Groq/Anthropic/Gemini SSE)
See docs/architecture.md and docs/dashboard-architecture.md for detailed diagrams.
Both just and make are supported. All recipes share the same names — swap just ↔ make freely. just adds recipe parameters and auto .env loading; make works without extra dependencies.
| Task | just |
make |
|---|---|---|
| Show all commands | just --list |
make help |
| Server | ||
| Start (background) | just server |
make server |
| Start (foreground) | just server-fg |
make server-fg |
| Stop / restart / status | just stop / restart / status |
make stop / restart / status |
| Tail logs / clear | just logs / logs-clear |
make logs / logs-clear |
| Testing | ||
| Run all tests | just test |
make test |
| Run specific file | just test test/lilbots/agent_test.exs |
— |
| Engine tests | just test-engine |
make test-engine |
| E2E (Playwright) | just test-e2e |
make test-e2e |
| All checks | just check |
make check |
| Code Quality | ||
| Format / lint | just format / lint |
make format / lint |
| Credo / Dialyzer | just credo / dialyzer |
make credo / dialyzer |
| Games | ||
| Debate | just debate "Should AI have rights?" |
make debate |
| Telephone | just telephone "Hello world" |
make telephone |
| Trivia | just trivia "History" |
make trivia |
385 tests across three layers:
- Unit/integration (
test/) — Agent, LLM providers, tools, meta preset engine, cost tracking - LiveView (
test/lilbots_web/live/) — DashboardLive and MetaPresetLive event handlers - E2E (
e2e/) — Playwright browser tests against a running server
Test support modules:
| Module | Purpose |
|---|---|
LiveCase |
LiveView test template with MockLLM setup and agent cleanup |
EngineCase |
Meta preset engine tests with debate helpers and prompt validation |
MockLLM |
In-process mock LLM with configurable response functions |
just test # All tests (or: make test)
just test test/lilbots/agent_test.exs # Specific file (just only)
just test-engine # Meta preset engine tests only
just test-e2e # Playwright e2e tests (requires running server)
just check # Format + credo + compile warnings + testlilbots/
├── lib/
│ ├── lilbots/
│ │ ├── agent.ex # Agent GenServer (chat, streaming, connections)
│ │ ├── agent_supervisor.ex # DynamicSupervisor for agent lifecycle
│ │ ├── cost_tracker.ex # Real-time LLM cost tracking (ETS)
│ │ ├── fleet.ex # Fleet/group prompt management
│ │ ├── llm.ex # LLM client with provider routing
│ │ ├── llm/
│ │ │ ├── anthropic.ex # Anthropic Messages API provider
│ │ │ ├── behaviour.ex # Provider behaviour contract
│ │ │ ├── gemini.ex # Google Gemini API provider
│ │ │ ├── tool_loop.ex # Recursive tool-use loop
│ │ │ ├── sse_parser.ex # SSE parser (OpenAI-compatible / Groq)
│ │ │ ├── sse_parser_anthropic.ex # SSE parser (Anthropic format)
│ │ │ └── sse_parser_gemini.ex # SSE parser (Gemini format)
│ │ ├── names.ex # Random name generator
│ │ ├── orchestrator.ex # Multi-agent coordination
│ │ ├── presets.ex # 78 agent personality presets
│ │ ├── presets_batch_1.ex # 20 additional presets (fun, personality)
│ │ ├── presets_batch_2.ex # 30 additional presets (fictional, professional, historical)
│ │ ├── meta_presets/
│ │ │ ├── engine.ex # Session state machine
│ │ │ ├── meta_preset.ex # Preset struct
│ │ │ ├── registry.ex # Meta preset registration
│ │ │ ├── topology.ex # Message routing rules
│ │ │ └── patterns/ # 11 interaction patterns
│ │ └── tools/ # 19 tool modules
│ └── lilbots_web/
│ ├── components/
│ │ ├── agent_card.ex # Agent grid cards
│ │ ├── agent_config_panel.ex # Sidebar config panel
│ │ ├── cost_display.ex # SVG cost badges and sparklines
│ │ ├── game_boards.ex # SVG game board rendering
│ │ ├── new_agent_modal.ex # Agent creation modal
│ │ ├── tutorial_modal.ex # Tutorial/mission briefing modal
│ │ └── wire.ex # SVG wire visualization
│ ├── helpers/
│ │ ├── markdown.ex # Markdown rendering with XSS sanitization
│ │ └── status_helpers.ex # Shared agent status display helpers
│ └── live/
│ ├── dashboard_live.ex # Main dashboard LiveView
│ ├── dashboard_live.html.heex # Dashboard template
│ ├── dashboard/
│ │ ├── fleet.ex # Fleet management handlers
│ │ ├── shuffle.ex # Shuffle/randomization handlers
│ │ ├── streaming.ex # Streaming response handlers
│ │ └── tutorial.ex # Tutorial flow handlers
│ └── meta_preset_live.ex # Meta preset session UI
├── test/ # 385 tests
├── e2e/ # Playwright e2e tests
└── docs/ # Architecture and design docs
Copy env.example to .env and set your API keys:
cp env.example .env
# Edit .env with your GROQ_API_KEY (required)
# Optionally add ANTHROPIC_API_KEY for Claude models
# Optionally add GEMINI_API_KEY for Gemini models
# Optionally add BRAVE_SEARCH_API_KEY for web search tool
# Optionally set LILBOTS_AGENT_COUNT to change startup agent count (default: 4)See env.example for all available environment variables including Anthropic, Gemini, and Brave Search configuration.
See docs/model-pricing.md for per-model token pricing and tier categories.