Whilly v3.x

📎 GitHub · 🏷 Тег v3-final · 📦 PyPI: whilly-orchestrator==3.3.0

Эта страница про v3.x — single-process версию. Распределённая v4 — это отдельный продукт, переписанный с нуля. v3.x в режиме поддержки (только критические багфиксы), но не выпиливается — для маленьких сценариев на одном ноутбуке она проще и удобнее.

Зачем нужно

Whilly v3 — это про сценарий «один человек, один ноутбук, один Claude, и куча задач». Утром составил план в JSON, нажал whilly, ушёл пить кофе. Вернулся через час — задачи сделаны, что не вышло — лежит в логе с понятным объяснением. Никаких серверов, никаких баз данных, никаких docker-compose — только Python и Claude CLI.

Само название — отсылка к технике Ralph Wiggum loop Geoff’а Huntley’а: «pick task → try → shout I’m helping! → repeat». Тупой бесконечный цикл, который удивительно хорошо работает на агентах. Whilly — это «умный младший брат Ральфа»: тот же цикл, но с TRIZ-анализатором, Decision Gate’ом (отказ от мусорных задач до запуска) и PRD-визардом (понять задачу прежде чем кидаться её решать).

Что внутри 

                  ┌──────────────────────────────────┐
                  │       JSON plan (tasks.json)      │
                  └─────────────────┬────────────────┘
                                    ▼
        ┌────────────────────────────────────────────────────┐
        │              whilly (Python process)                │
        │                                                     │
        │  TaskManager → orchestrator → tmux_runner ───┐      │
        │       ↑                                       │      │
        │  state_store ← reporter ← agent_runner ←──────┘      │
        │                                                     │
        │              Rich Live TUI dashboard                 │
        └─────────────────────┬──────────────────────────────┘
                               ▼
                       Claude CLI (subprocess)
                       в tmux-pane / worktree

Один процесс. Одна машина. Состояние на диске (.whilly_state.json, whilly_logs/whilly_events.jsonl). Параллелизм через tmux-панели или git-worktrees — каждый агент в своём изолированном воркспейсе.

Что делало v3 особенным

TRIZ-анализатор. Перед запуском задачи Whilly прогонял её через TRIZ-методологию — выискивал технические противоречия в формулировке. На выходе либо «задача чёткая, погнали», либо «вижу противоречие между X и Y, доуточни условие». Это убивало 30% задач, которые в обычном режиме сожгли бы 10 долларов токенов на бесполезных попытках.

Decision Gate. Прежде чем запускать LLM на задаче, Whilly спрашивал: «эта формулировка вообще выполнима?» Если описание — типа «улучшить производительность» (без метрик, без целевого числа, без what-good-looks-like) — задача отклонялась с понятным объяснением почему. Лучше отказать на старте, чем потратить час и получить результат, который никто не примет.

PRD-визард. Если задача большая и расплывчатая, Whilly запускал интерактивный сценарий: задавал уточняющие вопросы, формировал PRD-документ (Product Requirements Document), и из PRD’а уже автоматически выводил конкретные задачи. То есть «опиши идею → получи готовый план». Сильно недооценённая фича.

Self-healing. v3 умел детектить крэши, базовые ошибки в коде (NameError, ImportError) — и сам перезапускал пайплайн с фиксом. Не идеально, но в 70% случаев избавляло от утренней рутины «открыть лог, понять что упало, перезапустить».

Параллельный режим в tmux. До N агентов одновременно, каждый в своей tmux-панели. Можно реально посмотреть в живом режиме как несколько Claude’ов работают параллельно. Эстетический кайф плюс практическая польза — на простых задачах кратное ускорение.

Что работает

  • Импорт планов из JSON, GitHub Issues, Projects v2, Jira-проектов.
  • Бэкенды агентов: Claude CLI, OpenCode, claude_handoff (file-based RPC если нужно подключить человека вручную).
  • Live-дашборд в терминале с горячими клавишами (q quit, p pause, d detail, l logs, t tasks, h help).
  • Бюджеты: WHILLY_BUDGET_USD — Whilly останавливается когда счётчик токенов упирается в потолок.
  • Резюм: упал процесс — whilly --resume восстановит состояние из .whilly_state.json и продолжит с того же места.
  • Wall-clock timeout: задачи свыше N минут автоматически помечаются как failed.
  • Крос-платформа: тестировано на Linux/macOS/Windows.

Что я бы выбрал v4 вместо v3, если…

  • …нужно гонять Whilly на сервере, к которому подключаются разные ноутбуки.
  • …задач много, и не хочется ждать пока ноут разогревается под одного агента.
  • …критично, чтобы при крэше воркера задача не потерялась (на v3 если процесс упал между «начал» и «закончил» — приходится разбираться руками).
  • …нужен audit-trail в БД (а не json-файл, который легко потерять).
  • …хочется поставить только воркер на машинку без права писать в Postgres (на v3 такого нет — оно всё в одном процессе).

Если ничего из этого не нужно — v3 проще, легче в развёртывании и не требует ничего кроме pip install.

Что было неприятного в v3

Plan-level workspace по умолчанию — в v3.0..v3.2 при каждом запуске создавался отдельный git worktree для плана. Идея была защитить рабочее дерево от агентов. На практике сабпроцессы с абсолютными путями в .venv (TypeScript, pytest, ruff в редакторе) ломались на ровном месте, git status показывал странности, и агент тратил половину итерации разбираясь где он находится. С v3.3.0 выключили по умолчанию. Урок: фичу, которая меняет cwd сабпроцессов, нельзя дефолтить.

Один процесс — одна точка отказа. Если процесс умер посреди работы — всё. --resume помогает, но сценарий «упал между mark in_progress и mark done» теоретически может оставить задачу в подвешенном состоянии. На v4 это решено через visibility-timeout sweep, на v3 — никак.

Состояние в .whilly_state.json. Один файл, который читают и пишут одновременно несколько компонентов через атомарную замену. Работает, но если открыл его в редакторе посреди прогона — может что-нибудь сломать. На v4 это просто строка в Postgres.

Sleep на 5 секунд при старте (_show_startup_banner). Стоит до сих пор, потому что несколько тестов и операционных скриптов зависят от этой задержки. Каждый раз когда запускаешь — ждёшь 5 секунд просмотра баннера. Технический долг, который не получается выпилить без миграции зависимых скриптов.

Documentation drift. README на v3.3.0 написан для v3, и большая часть документации (Getting-Started.md, Self-Healing-Guide.md, Whilly-Usage.md) описывает именно v3-поведение. На v4 эти доки становятся «устаревшими по умолчанию» — нужно либо переписывать, либо явно помечать. Сейчас явно помечены, переписывание deferred.

Что дальше

  • v3.x line зафиксирована на тэге v3-final. Только критические багфиксы.
  • Если стоит v3 и думаешь обновляться: Миграция с v3 на v4 — там подробный mapping env-vars, CLI-команд и breaking changes.
  • Если хочется почитать про новую распределённую архитектуру: Whilly v4.