convez.ai
AgenteAutomaçãoIntermediário
ellmos-ai

MarbleRun / llmauto

ellmos-ai/MarbleRun

Orquestração local-first de cadeias de agentes Claude Code em Python

Ver no GitHub
BomPluginScore · de 0 a 100

Framework 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/MarbleRun

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 1 semana
Versão
v0.1.3
Issues abertas
2
Contribuidores
2

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.

MarbleRun banner

llmauto -- LLM Automation Framework (MarbleRun)

🇩🇪 Deutsche Version

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:

PhraseWhy it matters
ellmos MarbleRunDistinguishes this repo from confidential-computing and game projects named MarbleRun
llmauto Claude Code automationFinds the package and CLI name used in code
MarbleRun LLM agent chainsDescribes the central chain-execution pattern
local-first multi-agent orchestration PythonCaptures the zero-dependency local automation use case
Claude Code agent chain runnerMatches users searching for unattended Claude Code worker/reviewer/controller loops
llmauto autonomous agent loopCombines 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


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_hours exceeded
  • max_rounds reached
  • status.txt contains "STOPPED" or "ALL_DONE"
  • max_consecutive_blocks consecutive BLOCK states
  • Manual stop via llmauto chain stop

State Files

Each chain maintains persistent state in state/<chain-name>/:

FilePurpose
status.txtREADY, RUNNING, STOPPED, ALL_DONE, BLOCKED
round_counter.txtCurrent round number
handoff.mdContext handoff between links
start_time.txtWhen the chain was started

Chain Configuration Schema

FieldTypeDescription
descriptionstringHuman-readable description
modestringloop (repeat), once (single pass), deadend (single pass)
max_roundsintMaximum number of complete cycles
runtime_hoursfloatMaximum runtime in hours
deadlinestringHard deadline (ISO date)
linksarrayOrdered list of chain links

Link Configuration

FieldTypeDescription
namestringUnique link identifier
rolestringworker, reviewer, controller
modelstringClaude model ID
promptstringPrompt template filename or inline text
continueboolUse --continue flag (persistent session)
fallback_modelstringFallback model if primary fails
until_fullboolAdd context-limit awareness suffix
telegram_updateboolSend 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)

SettingDefault
default_modelclaude-sonnet-4-6
default_permission_modedontAsk
default_allowed_toolsRead, Edit, Write, Bash, Glob, Grep
default_timeout_seconds7200 (2h)
telegram.enabledfalse

Included Example Chains

llmauto ships with several production-tested chain configurations:

ChainPatternDescription
worker-reviewer-loopTemplateBasic 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?

MarbleRunOpenClaw
FocusAutonomous multi-agent orchestration -- make LLMs actPersonal AI assistant -- conversational gateway
ExecutionMulti-agent chains: Worker -> Reviewer -> Controller loopsSingle-agent responding to messages
AutonomyFully autonomous -- chains run for hours unattended (rounds, deadlines, shutdown conditions)Reactive -- responds to user input, cron/webhooks for automation
Multi-modelMix Opus, Sonnet, Haiku in one chain with role-based assignmentModel selection per session, failover support
StateHandoff files, round counters, persistent sessions (continue mode)Session history with /compact summarization
DependenciesZero -- pure Python stdlib + Claude Code CLINode.js 22+, numerous npm packages
LicenseMITMIT

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.

Ver o original no GitHub

Bom para

Relacionados