.Choola

An automation programming framework for AI coding agents.
github.com/igrosny/choola

What it is

Choola is a Python framework for building automations with coding agents like Claude Code — not around them. You describe an automation in plain language, an agent scaffolds it into a graph of single-file Python nodes, and the engine runs it with full traceability, cost discipline, and a deterministic execution model that agents can inspect and improve over time.

A workflow is a folder of Python files. A node is one file. Nodes pass JSON payloads. That's it.

Quick start

Install from PyPI, initialize a project, and launch the visual editor:

pip install choola

choola init     # workflows/, choola.db, .claude/ slash commands
choola start    # editor at http://localhost:5000

From there, build a workflow in the canvas or describe it to Claude Code:

/workflow build a workflow that takes an uploaded PDF, summarizes
it with Claude, and emails me the summary

Or run an existing workflow headlessly:

choola run my-workflow --payload '{"key": "value"}'
choola replay my-workflow <run_id> <node_id>   # re-run one node from saved input
choola dream                                  # train XGBoost classifiers from history

Features

  1. Agent-generated by design. Ships with Claude Code slash commands (/workflow, /node, /debug, /replay) that turn English into working workflows.
  2. Workflows are MCP tools. A single JSON-RPC endpoint at /mcp publishes every workflow as a callable tool, with optional bearer-token auth.
  3. Single-file node isolation. Every node is one .py file. No cross-node imports, no shared mutable state — only a JSON payload through execute(payload, context).
  4. Full execution traces. Each run writes an evaluation JSON with per-node input, output, timing, token usage, and full traceback on error.
  5. Deterministic flow, AI inside. The DAG is fixed and topologically sorted; creativity lives inside nodes, not in the orchestration.
  6. Cost guardrails in the contract. Nodes declare a @cost tag; paid loops require max_items and max_consecutive_errors; engine-level token circuit breakers enforce per-run and per-hour caps.
  7. Replay, don't re-run. Re-execute a single node against its previously saved input — never pay for the full pipeline twice while debugging.
  8. Self-training classifier nodes. LLML falls through cache → local XGBoost → real LLM. choola dream trains a per-node model from history so loops get cheaper over time.
  9. Branching, merging, conditional routing. Fan-out, fan-in, and runtime branch activation via {"__active_branches__": [...]}. Diamond patterns work correctly.
  10. Per-workflow SQLite, vector DB, encrypted credentials. State when you want it; none of it hidden. Each workflow gets its own isolated SQLite and ChromaDB.
  11. Visual editor + CLI, same source of truth. The editor renders the same Python files the CLI runs. A built-in terminal pane runs Claude Code scoped to the active workflow.

How to build workflows

A new walkthrough each week. Each one starts from choola init and ends with a workflow you can run.