MarbleRun / llmauto
ellmos-ai/MarbleRun
Orquestração local-first de cadeias de agentes Claude Code em Python
Ver no GitHubFramework Python de automação para orquestração de cadeias de agentes LLM autônomos. Executa múltiplos agentes em sequência (workers, reviewers, controllers) que passam contexto via arquivos de handoff, funcionando como uma "corrida de bolinhas" onde cada agente tem um papel específico na cadeia.
Instalação
npx convez-ai ellmos-ai/MarbleRun1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar fluxos de trabalho multi-agente sem dependências externas
- Criar loops de execução autônoma de agentes com papéis distintos (worker/reviewer/controller)
- Orquestrar tarefas complexas passando contexto entre agentes via arquivos
Veredito

Ferramenta madura e bem-pensada para orquestração de agentes LLM locais com padrão elegante de handoff. Ideal para automação complexa que não requer cloud, mas exige curva de aprendizado moderada no design de cadeias JSON e papéis de agentes.
README
A tradução para o português deste README ainda está na fila.
llmauto -- LLM Automation Framework (MarbleRun)
Automation & workflow system by ellmos-ai.
Universal automation tool for LLM agents. Chain execution, prompt management, autonomous work loops.
Canonical search name: ellmos MarbleRun or llmauto.
This repository is not the confidential-computing project edgelesssys/marblerun
and not a marble-run game toolkit; it is a Python/Claude Code automation
framework for autonomous LLM agent chains.
Author: Lukas Geiger | License: MIT | Python: 3.10+
What is llmauto?
llmauto orchestrates autonomous LLM agent chains ("marble runs"). Multiple agents work in sequence -- workers execute tasks, reviewers check results, controllers coordinate -- passing context via handoff files.
Think of it as a marble run: the marble (context) rolls from link to link in a loop, with each link being an LLM agent with a specific role and prompt.
Best Search Phrases
Use these phrases when looking for the project in search engines, GitHub search, LLM tool indexes, or internal automation docs:
| Phrase | Why it matters |
|---|---|
ellmos MarbleRun | Distinguishes this repo from confidential-computing and game projects named MarbleRun |
llmauto Claude Code automation | Finds the package and CLI name used in code |
MarbleRun LLM agent chains | Describes the central chain-execution pattern |
local-first multi-agent orchestration Python | Captures the zero-dependency local automation use case |
Claude Code agent chain runner | Matches users searching for unattended Claude Code worker/reviewer/controller loops |
llmauto autonomous agent loop | Combines the CLI/package name with the core automation pattern |
Discovery Context
MarbleRun is best discovered through its CLI/package name llmauto plus the
use case: Claude Code automation, agent-chain runner, local-first multi-agent
orchestration, and handoff-based autonomous work loops. The bare name
MarbleRun is intentionally disambiguated because public search results also
include confidential-computing infrastructure and physical marble-run projects.
Key Features
- Chain Execution: Define multi-agent chains in JSON, run them autonomously
- Marble Run Pattern: Sequential agent loops with handoff-based context passing
- Multi-Model Support: Mix Claude Opus, Sonnet, and Haiku in a single chain
- Role System: Workers, Reviewers, Controllers with skip-if-not-assigned patterns
- State Management: Persistent round counters, handoff files, stop/resume support
- Pipe Mode: Single LLM calls from the command line
- Background Execution: Start chains in separate terminal windows
- Telegram Notifications: Optional status updates via Telegram bot
- Zero Dependencies: Pure Python stdlib (subprocess, json, pathlib, sqlite3)
Requirements
- Python 3.10+
- Claude Code CLI (
claudecommand available in PATH)
Installation
git clone https://github.com/ellmos-ai/MarbleRun.git
cd MarbleRun
# Run directly (no install needed)
python -m llmauto --help
# Or install as package
pip install -e .
llmauto --help
Quick Start
1. Create a Chain Definition
Create a JSON file in chains/ (e.g. chains/my-chain.json):
{
"description": "Simple worker-reviewer loop",
"mode": "loop",
"max_rounds": 5,
"runtime_hours": 2,
"links": [
{
"name": "worker",
"role": "worker",
"model": "claude-sonnet-4-6",
"prompt": "worker_prompt.txt"
},
{
"name": "reviewer",
"role": "reviewer",
"model": "claude-opus-4-6-20250918",
"prompt": "reviewer_prompt.txt",
"continue": true
}
]
}
2. Create Prompt Templates
Place prompt files in prompts/ (e.g. prompts/worker_prompt.txt):
You are a software development worker. Read the handoff file at
state/my-chain/handoff.md for your current assignment.
Execute the assigned tasks, then write a handoff for the reviewer:
- What you completed
- What needs review
- Any blockers
3. Run the Chain
# Start in foreground
python -m llmauto chain start my-chain
# Start in background (opens new terminal window)
python -m llmauto chain start my-chain --bg
# Check status
python -m llmauto chain status my-chain
# Stop gracefully (after current link finishes)
python -m llmauto chain stop my-chain "Reason for stopping"
# View logs
python -m llmauto chain log my-chain 50
# Reset state (back to round 0)
python -m llmauto chain reset my-chain
4. Pipe Mode (Single Calls)
# Direct prompt
python -m llmauto pipe "Explain quantum computing in 3 sentences"
# From file
python -m llmauto pipe -f prompt.txt
# With model override
python -m llmauto pipe "Hello" --model claude-opus-4-6-20250918
Chain Architecture
How Marble Runs Work
Round N:
[Link 1: Worker] --executes tasks--> writes handoff.md
|
[Link 2: Reviewer] --reads handoff--> reviews + fixes --> writes handoff.md
|
[Link 3: Controller] --reads handoff--> coordinates --> writes handoff.md
|
Round N+1 ...
Shutdown Conditions
A chain stops when any of these conditions are met:
runtime_hoursexceededmax_roundsreachedstatus.txtcontains "STOPPED" or "ALL_DONE"max_consecutive_blocksconsecutive BLOCK states- Manual stop via
llmauto chain stop
State Files
Each chain maintains persistent state in state/<chain-name>/:
| File | Purpose |
|---|---|
status.txt | READY, RUNNING, STOPPED, ALL_DONE, BLOCKED |
round_counter.txt | Current round number |
handoff.md | Context handoff between links |
start_time.txt | When the chain was started |
Chain Configuration Schema
| Field | Type | Description |
|---|---|---|
description | string | Human-readable description |
mode | string | loop (repeat), once (single pass), deadend (single pass) |
max_rounds | int | Maximum number of complete cycles |
runtime_hours | float | Maximum runtime in hours |
deadline | string | Hard deadline (ISO date) |
links | array | Ordered list of chain links |
Link Configuration
| Field | Type | Description |
|---|---|---|
name | string | Unique link identifier |
role | string | worker, reviewer, controller |
model | string | Claude model ID |
prompt | string | Prompt template filename or inline text |
continue | bool | Use --continue flag (persistent session) |
fallback_model | string | Fallback model if primary fails |
until_full | bool | Add context-limit awareness suffix |
telegram_update | bool | Send Telegram notification after this link |
Advanced Patterns
Skip-If-Not-Assigned
For chains where a controller assigns work to either an Opus or Sonnet worker:
{
"links": [
{"name": "controller", "role": "controller", "model": "opus"},
{"name": "opus-worker", "role": "worker", "model": "opus"},
{"name": "sonnet-worker", "role": "worker", "model": "sonnet"}
]
}
The controller writes ASSIGNED: opus or ASSIGNED: sonnet in the handoff.
The non-assigned worker reads the handoff and skips immediately.
Continue Mode
Links with "continue": true maintain a persistent Claude Code session
in a dedicated workspace directory. Each invocation continues the previous
conversation, preserving full context.
Template Variables
Prompts support {HOME} (Windows path) and {BASH_HOME} (Unix path)
placeholders that are resolved at runtime.
Project Structure
llmauto/
llmauto.py Main CLI entry point
config.json Global configuration
core/
runner.py Claude CLI wrapper (subprocess, env, fallback)
config.py Config management (chains, global)
state.py State management (handoff, rounds, shutdown)
modes/
chain.py Marble run engine
chains/ Chain definitions (JSON)
prompts/ Prompt templates per chain
state/ Runtime state per chain (gitignored)
logs/ Runtime logs (gitignored)
templates/ Chain pattern templates
docs/ Documentation
Global Configuration (config.json)
| Setting | Default |
|---|---|
default_model | claude-sonnet-4-6 |
default_permission_mode | dontAsk |
default_allowed_tools | Read, Edit, Write, Bash, Glob, Grep |
default_timeout_seconds | 7200 (2h) |
telegram.enabled | false |
Included Example Chains
llmauto ships with several production-tested chain configurations:
| Chain | Pattern | Description |
|---|---|---|
worker-reviewer-loop | Template | Basic 2-link worker/reviewer pattern |
See chains/ for the full set of included chain definitions.
See Also: OpenClaw
MarbleRun makes LLMs act -- autonomous multi-agent chains where workers, reviewers, and controllers collaborate in loops. How does it compare to OpenClaw?
| MarbleRun | OpenClaw | |
|---|---|---|
| Focus | Autonomous multi-agent orchestration -- make LLMs act | Personal AI assistant -- conversational gateway |
| Execution | Multi-agent chains: Worker -> Reviewer -> Controller loops | Single-agent responding to messages |
| Autonomy | Fully autonomous -- chains run for hours unattended (rounds, deadlines, shutdown conditions) | Reactive -- responds to user input, cron/webhooks for automation |
| Multi-model | Mix Opus, Sonnet, Haiku in one chain with role-based assignment | Model selection per session, failover support |
| State | Handoff files, round counters, persistent sessions (continue mode) | Session history with /compact summarization |
| Dependencies | Zero -- pure Python stdlib + Claude Code CLI | Node.js 22+, numerous npm packages |
| License | MIT | MIT |
In short: OpenClaw connects LLMs to conversations. MarbleRun connects LLMs to each other -- creating autonomous work loops where agents collaborate, review, and iterate without human intervention.
License
MIT License. See LICENSE.
Author
Lukas Geiger -- github.com/lukisch
Haftung / Liability
Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß § 521 BGB auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gelten die Haftungsausschlüsse der MIT-Lizenz.
Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.
This project is an unpaid open-source donation. Liability is limited to intent and gross negligence (§ 521 German Civil Code). Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.