zubble

A minimal, hackable agentic harness for LLM-driven repair and coding tasks.

zubble combines the simplicity of mini-swe-agent, the anti-loop discipline of Ralph Wiggum, the doom-loop detection of ZeroStack, and hard-won lessons from FestBench's ScenarioBench — in ~200 lines of readable Python.

Why?

Heavyweight agent platforms (Goose, Crush, OpenHands) are powerful but opaque. zubble is the opposite: a loop you can read in one sitting, extend with a subclass, and run against any endpoint — no framework tax.

It was designed to make five failure modes structurally impossible:

1. Conversation simulation — stop sequences + proper messages array
2. Degenerate repetition — in-stream repetition detection + doom-loop detector
3. Context poisoning — response truncation + fresh-context reset
4. Budget exhaustion — per-call maxtok caps by thinking level
5. Amnesia — a disk-persisted trial journal that survives context resets

Quickstart

# Install (when published)
pip install zubble-agent

# Run against any OpenAI-compatible endpoint (llama.cpp, vLLM, Ollama)
zubble run \
  --endpoint http://192.168.5.117:8000 \
  --task "fix the kubelet config on node-1" \
  --env docker --env-container bastion-03 \
  --level xhigh --minutes 15

# Run against a hosted API
zubble run --model anthropic/claude-sonnet-4 --task "refactor auth" --env local

# Run as a Ralph Wiggum loop (fresh context each iteration)
zubble loop --task spec.md --max-iterations 20 --fresh-context

# Run with trial journal + cross-run memory
zubble run --task "debug cert_expiry" --env kubectl --memory-dir ~/.zubble/memory

Key features

• Stop sequences on every API call — prevents conversation simulation
• In-stream repetition detection — aborts degenerate output mid-generation
• Proper messages array — never flattens to User:/Assistant: text
• Doom-loop detection — 3 identical commands triggers a warning
• Fresh-context reset — on degenerate loop, restart with journal summary
• Trial journal — disk-persisted record of what worked and what didn't
• Thinking level control — chat_template_kwargs for reasoning models
• Per-call maxtok by level — off/low/medium/xhigh budgets
• Temperature flag — default 0 for reproducibility, overridable
• Pluggable — Model, Environment, Observer, Protocol are interfaces
• MIT licensed — no copyleft, no vendor lock-in

Architecture

Four pluggable components:

Component	Role	Examples
Model	LLM API client	OpenAIModel, LitellmModel, CliModel
Environment	Command execution sandbox	LocalEnv, DockerEnv, KubectlEnv
Observer	Loop/degeneration detector	DoomLoopObserver, TextRepetitionObserver
Journal	Disk-persisted trial memory	TrialJournal

Plus Protocol classes that define task-specific message templates (repair, SWE-bench, custom).

Design document

See DESIGN.md for the full architecture, control flow, feature catalog, comparison table, and roadmap.

License

MIT — see LICENSE.

Attribution

zubble draws from mini-swe-agent (MIT, Princeton/Stanford), Ralph Wiggum (MIT, fstandhartinger / Geoffrey Huntley), ZeroStack (GPL-3.0, gi-dellav), and FestBench's ScenarioBench harness.