claubee 0.1.0

Sequential AI pipeline runner with per-step model switching and interactive error recovery

Claubee

Sequential AI pipeline runner with per-step model switching and interactive error recovery.

Claubee lets you define a sequence of AI-powered steps in a single TOML file. Each step can use a different model and backend — Anthropic or Ollama — and the output of each step is automatically passed as context to the next. When a step fails, Claubee gives you an interactive menu to retry, inject a correction, edit the prompt, skip, or abort.

---

Installation

pip install claubee

Requires Python 3.10+.

---

Quick Start

1. Copy examples/example_config.toml to your project directory
2. Edit the steps to match your use case
3. Run:

claubee run example_config.toml

---

Full Example

Here is a complete pipeline.toml for a real-world scenario: reviewing and documenting a codebase, then running a deep multi-stage analysis, and finally producing a build report. It demonstrates single prompts, a file-based prompt, and sub-prompts in one pipeline.

[global]
project_dir = "C:/Projects/MyApp"
context_log  = "C:/Projects/MyApp/claubee_run_context.txt"
context_mode = "full"
ollama_base_url = "http://localhost:11434"

# Step 1 — Understand the codebase with Anthropic
[[steps]]
name = "Understand Codebase"
backend = "anthropic"
model = "claude-sonnet-4-6"
prompt = """
Read the files in this directory. Give a high-level summary of what this
project does, its architecture, key files, and any obvious technical debt.
"""
allowed_tools = ["Read", "Glob", "Grep"]
permission_mode = "acceptEdits"
stream = true
context_mode = "full"

# Step 2 — Write docs using Ollama (cheaper model for bulk writing)
[[steps]]
name = "Write Documentation"
backend = "ollama"
model = "gemma3:12b"
prompt = """
Using the architecture summary from the prior context, write a comprehensive
DOCS.md covering: Overview, Architecture, Key Components, and Developer Setup.
Save the file as DOCS.md in the project root.
"""
allowed_tools = ["Read", "Write"]
permission_mode = "acceptEdits"
stream = true
context_mode = "summary"

# Step 3 — Prompt loaded from a file in the project directory.
# REVIEW_CHECKLIST.md contains a detailed, versioned list of review criteria
# maintained by the team — keeping it outside the TOML makes it easy to update
# without touching the pipeline config.
[[steps]]
name = "Security and Quality Review"
backend = "anthropic"
model = "claude-sonnet-4-6"
prompt = """
Read the file REVIEW_CHECKLIST.md in this directory. It contains the full
review criteria for this project. Follow every item in that checklist exactly,
examining the relevant source files for each point. Write your findings to
REVIEW_REPORT.md.
"""
allowed_tools = ["Read", "Write", "Glob", "Grep"]
permission_mode = "acceptEdits"
stream = true
context_mode = "summary"

# Step 4 — Multi-stage build analysis using sub_prompts.
# Each sub-prompt runs in sequence; Anthropic caches the shared prefix,
# keeping token costs lower than four independent calls would be.
[[steps]]
name = "Build and Test Analysis"
backend = "anthropic"
model = "claude-sonnet-4-6"
sub_prompts = [
    "Run `dotnet build` and capture the full output. List every warning and error.",
    "For each build error found, locate the relevant source file and explain the root cause.",
    "Attempt to fix the errors. Apply the minimal change needed for each one.",
    "Run `dotnet build` again to confirm the fixes. Report which errors were resolved and which remain.",
]
session_summary_prompt = """
Summarise the build result: how many errors were found, how many were fixed,
and what (if anything) still needs manual attention. Keep it under 150 words.
"""
allowed_tools = ["Read", "Edit", "Bash", "Glob"]
permission_mode = "acceptEdits"
stream = true
context_mode = "full"

# Step 5 — Final summary with Ollama
[[steps]]
name = "Final Summary"
backend = "ollama"
model = "gemma3:12b"
prompt = """
Review all prior context from this pipeline run. Write a concise executive
summary covering: what the project does, documentation produced, review
findings, build status, and any outstanding issues. Save it as SUMMARY.md.
"""
allowed_tools = ["Read", "Write"]
permission_mode = "acceptEdits"
stream = true
context_mode = "none"

Run it with:

claubee run pipeline.toml

Resume from a specific step after a failure:

claubee run pipeline.toml --start-from "Build and Test Analysis"

The rolling context is saved to claubee_run_context.txt after each step completes, so --start-from can pick up exactly where the pipeline left off.

---

How It Works

Claubee uses the Claude Code SDK as its single runner for all steps. Backend switching between Anthropic and Ollama is handled entirely via environment variables — no separate runner code per backend.

Before each step, Claubee sets the appropriate env vars:

• Anthropic: uses ANTHROPIC_API_KEY (or your Claude Code login session)
• Ollama: sets ANTHROPIC_AUTH_TOKEN=ollama, ANTHROPIC_BASE_URL=http://localhost:11434, and clears the API key

The SDK sees a valid Anthropic-compatible API regardless of which backend is active. After each step, the previous env state is restored exactly.

---

Config Reference

[global] section

Field	Type	Required	Default	Description
project_dir	string	yes	—	Working directory for all steps
context_log	string	no	./claubee_context.txt	File path to save rolling context after each step
context_mode	string	no	"full"	Default context strategy: "full", "summary", or "none"
ollama_base_url	string	no	"http://localhost:11434"	Base URL for Ollama — change if running on a different host

[[steps]] entries

Field	Type	Required	Default	Description
name	string	yes	—	Display name for banners and error messages
backend	string	yes	—	"anthropic" or "ollama"
model	string	yes	—	Model ID (e.g. "claude-sonnet-4-6", "gemma3:12b")
prompt	string	one of	—	Single prompt for this step. Mutually exclusive with sub_prompts.
sub_prompts	list[string]	one of	—	Multiple sequential prompts sharing session context. Anthropic only.
session_summary_prompt	string	no	—	Optional final prompt whose output is appended to the pipeline context (used with sub_prompts)
allowed_tools	list[string]	no	["Read"]	Claude Code SDK tools pre-approved for this step
permission_mode	string	no	"acceptEdits"	SDK permission mode: "acceptEdits", "bypassPermissions", "dontAsk", "default"
stream	bool	no	true	Stream output token-by-token to the terminal
context_mode	string	no	inherits global	"full" / "summary" / "none" — how this step's output is appended to pipeline context

Sub-prompts

A step with sub_prompts runs multiple prompts sequentially within the same conceptual session. Each sub-prompt receives the accumulated output of all prior sub-prompts as context. This is useful for multi-stage reasoning where each stage builds on the previous one.

Only the final sub-prompt's output is appended to the rolling pipeline context for downstream steps — unless session_summary_prompt is defined, in which case that output is used instead.

[[steps]]
name = "Deep Analysis"
backend = "anthropic"
model = "claude-sonnet-4-6"
sub_prompts = [
    "Identify the three most complex areas of this codebase.",
    "For each area, explain the risks and complexity drivers.",
    "Propose the single most impactful refactoring.",
]
session_summary_prompt = "Summarise all three areas and the top recommendation in 100 words."
allowed_tools = ["Read", "Glob", "Grep"]
context_mode = "summary"

---

Backend Setup

Anthropic

Either set your API key:

export ANTHROPIC_API_KEY=sk-ant-...
claubee run config.toml

Or pass it directly:

claubee run config.toml --api-key sk-ant-...

Or omit it entirely — if you're logged in to Claude Code, the SDK uses your session automatically.

Ollama

1. Install Ollama: https://ollama.com
2. Pull a model: ollama pull gemma3:12b
3. Start the server: ollama serve
4. Use backend = "ollama" in your step config

If Ollama runs on a non-default host or port, set ollama_base_url in [global].

---

CLI Reference

claubee run <config_file> [OPTIONS]

Option	Description
--api-key TEXT	Anthropic API key. Overrides ANTHROPIC_API_KEY env var.
--start-from TEXT	Step name to resume from. Loads saved context log automatically.
--dry-run	Print assembled prompts and config without calling any API.
--help	Show usage.

Examples

# Standard run
claubee run myconfig.toml

# With explicit API key
claubee run myconfig.toml --api-key sk-ant-abc123

# Resume from a specific step (loads context log automatically)
claubee run myconfig.toml --start-from "Build and Test"

# Preview what would run without calling any API
claubee run myconfig.toml --dry-run

---

Error Recovery

When a step fails, Claubee displays an interactive menu:

╔══════════════════════════════════════════════════════════╗
║  STEP FAILED: Build and Test  (step 3 of 4)             ║
╠══════════════════════════════════════════════════════════╣
║  Backend: anthropic  |  Model: claude-sonnet-4-6        ║
║                                                          ║
║  Error:                                                  ║
║  CS0103: The name 'AuthService' does not exist           ║
╚══════════════════════════════════════════════════════════╝

What would you like to do?
  [r] Retry the step as-is
  [i] Inject a correction and retry
  [e] Edit the step prompt and retry
  [s] Skip this step and continue
  [q] Quit pipeline

• Retry (r) — reruns the step unchanged; useful for transient failures
• Inject (i) — prepend a correction note and the error to the prompt before retrying
• Edit (e) — interactively rewrite the step prompt before retrying
• Skip (s) — mark the step as skipped and move on; a skip note is added to context
• Quit (q) — save context and exit with code 1

If a retry also fails, the menu is shown again. There is no automatic retry limit.

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes — keep the code simple and readable
4. Run pytest tests/ to verify
5. Open a pull request

The codebase is intentionally straightforward. Each concern lives in a single file and the data flow is linear: config → preflight → pipeline → steps → context.