Zrb Logo

🤖 Zrb: A Coding Agent With a Build System Inside

Zrb is a terminal coding agent you can wire into a build pipeline.

The agent part you already know: zrb llm chat is a full coding session in your terminal.

The other half is why Zrb exists. A skill can tell an agent to run the tests before deploying; a DAG makes it impossible not to. Zrb ships both — same file, same language, one pip install.

Contribution Guidelines | Report an Issue

1. Start where you'd start with any coding agent

pip install zrb
export OPENAI_API_KEY="your-key-here"   # or Anthropic, Gemini, Ollama, OpenRouter, ...

zrb llm chat

That's a full agent session: it reads and writes files, runs commands behind a permission gate, searches the web, and remembers the conversation across restarts. If you already have .claude/skills/ or CLAUDE.md in the repo, it picks them up.

Zrb Chat

For most days, this is the whole product. Stop reading here if that's what you came for.

2. Then you hit the thing prompting can't fix

You write a skill: "always run the tests before deploying." It works. Usually.

Then one run the model decides the tests are unrelated to the change. Another run it runs them, misreads a green summary under a red failure, and deploys anyway. A third run it deploys to staging because the prompt didn't say which environment. Nothing crashed — the agent did what it thought you meant, and you find out on Monday.

The problem isn't prompt quality. It's that a skill is advice, and some steps need to be a guarantee. So write those as a graph instead:

# zrb_init.py
from zrb import cli, CmdTask, LLMTask

write_fix = LLMTask(
    name="write-fix",
    message="Read the failing test output and fix the bug in src/.",
)
run_tests = CmdTask(name="run-tests", cmd="pytest -x")
deploy = CmdTask(name="deploy", cmd="./deploy.sh production")

cli.add_task(deploy)

write_fix >> run_tests >> deploy   # the agent proposes; the pipeline decides

zrb deploy

run-tests is not a suggestion the model can reason its way around. It is an edge in a graph. If pytest exits non-zero, deploy never starts, and zrb deploy exits with pytest's own exit code — which is what your CI actually branches on.

This is the part no amount of prompt engineering reaches, and it's why the agent lives inside an automation framework instead of the other way around:

The agent is one node, not the administrator. Its answer flows downstream through XCom and gets checked by the next step.
Readiness is a loop, not a request. HttpCheck/TcpCheck wait for a service to actually come up. "Wait until it's ready" is not a prompt-able behavior.
Failure is a number. Tasks exit with the underlying command's code, so CI can tell a lint failure from a deploy failure.
Scheduled and triggered runs have no one to ask. At 3am there is nobody to approve a tool call, so the boundaries have to be structural.

3. And sometimes you just want the one command

No session, no pipeline, no config:

zrb please "find every file over 100MB in this repo"

find . -type f -size +100M
📋 Copied to clipboard

It runs on the small model, answers in a couple of seconds, and puts the result on your clipboard instead of running it. Same install, same API key, none of the ceremony.

4. A fuller example: let the agent draw your codebase

Same shape as section 2, with a real payoff: an LLMTask reads your source and writes a Mermaid diagram, then a CmdTask renders it to PNG. The agent does the part that needs judgment; the shell does the part that needs to be exact.

Prerequisites

An LLM API key, set as in section 1 (export OPENAI_API_KEY="your-key-here"; OpenAI is the default provider).
Mermaid CLI, which renders Mermaid scripts to images:
```
npm install -g @mermaid-js/mermaid-cli
```

Define the pipeline

Add the following to your existing zrb_init.py file (or create a new one if you prefer to keep examples separate):

# zrb_init.py (continued)
from zrb import cli, LLMTask, CmdTask, StrInput, Group, Tpl
from zrb.llm.tool.code import analyze_code
from zrb.llm.tool.file import write_file

# Create a group for Mermaid-related tasks
mermaid_group = cli.add_group(Group(
    name="mermaid",
    description="🧜 Mermaid diagram related tasks"
))

# Task 1: Generate a Mermaid script from your source code using an LLM
make_mermaid_script = mermaid_group.add_task(
    LLMTask(
        name="make-script",
        description="Create a mermaid diagram from source code in the current directory",
        input=[
            StrInput(name="dir", default="./"),
            StrInput(name="diagram", default="state-diagram"),
        ],
        message=(
            "Read all necessary files in {ctx.input.dir}, "
            "make a {ctx.input.diagram} in mermaid format. "
            "Write the script into `{ctx.input.dir}/{ctx.input.diagram}.mmd`"
        ),
        tools=[analyze_code, write_file],
    )
)

# Task 2: Convert the Mermaid script into a PNG image using CmdTask
make_mermaid_image = mermaid_group.add_task(
    CmdTask(
        name="make-image",
        description="Create a PNG from a mermaid script",
        input=[
            StrInput(name="dir", default="./"),
            StrInput(name="diagram", default="state-diagram"),
        ],
        cmd=Tpl("mmdc -i '{ctx.input.diagram}.mmd' -o '{ctx.input.diagram}.png'"),
        cwd=Tpl("{ctx.input.dir}"),
    )
)

# Set up the dependency: the image task runs after the script is created
make_mermaid_script >> make_mermaid_image

Run it

From any project with source code:

git clone https://github.com/someuser/my-python-project.git
cd my-python-project
zrb mermaid make-image

Zrb asks for the directory and diagram name; press Enter to accept the defaults (./ and state-diagram). The agent analyzes your code and writes the Mermaid script, then mmdc renders it to a PNG.

State Diagram

🔥 Why Zrb?

🤖 A coding agent you program in Python. Tools, hooks, prompts, permission policies and history processors are plain Python in your zrb_init.py — not a config format, not a separate SDK.
🔒 Determinism where it matters. Put the model between deterministic steps and keep approvals, sandboxing and ordering under your control instead of the model's judgment.
🐍 Pure Python, no DSL. Tasks are objects; >> is the dependency operator.
💻 Terminal, web UI, or CI. The same task definition runs in all three.
🧩 Bring your Claude Code assets. Skills, hooks and MCP servers work as-is.
🌍 Open source, and white-labelable into your own branded CLI.

🖥️ Try the Web UI

zrb server start

Open http://localhost:21213. The server binds to 127.0.0.1 by default, so the UI is reachable only from the local machine. Full details: Web UI Guide.

Safety boundary: Zrb's web UI can start and control automation tasks, so it is not intended to be exposed publicly without deliberate hardening. If you set ZRB_WEB_HTTP_HOST to a non-loopback address, enable authentication and replace the documented default admin password and secret key with unique values. Startup warnings call out unsafe network-exposed configurations; see the Web UI Guide before using a shared or public bind.

Zrb Web UI

🧩 Program Your AI Agent

zrb llm chat works out of the box — but the moment you need it to do something specific, you don't reach for a config file or a separate SDK. You write Python, in the same file where you define the rest of your automation.

Every part of the agent is a value you can supply or a callable you can register:

You want to…	You write a…
Give the agent abilities	custom tool — a plain Python function it can call in-process
React to what it does	lifecycle hook — fires on tool calls, prompts, session start/end
Gate dangerous actions	permission policy / async approval channel
Inject live context into the prompt	dynamic prompt section — a `lambda ctx: ...` evaluated per request
Keep long conversations affordable	history processor — prune, redact, or summarize the message history
Route by cost or task	a model callable — pick the model per request

Example: a custom tool the agent calls in-process

from zrb import cli, LLMChatTask

# A normal Python function becomes a tool — typed args + docstring are the spec.
async def get_open_incidents(team: str) -> str:
    """Return the current open incidents for a given team."""
    return my_oncall_db.query(team)  # your code, running in-process

chat = LLMChatTask(name="ops-chat", tools=[get_open_incidents])
cli.add_task(chat)

The part nothing else does: the agent is a pipeline node

Because an LLMTask is just a Zrb task, you can wire it between deterministic steps. Its answer flows downstream through XCom, and your tools can call straight into your codebase:

fetch_ticket >> triage_with_llm >> route_to_team

👉 Full walkthrough and every hook in one place: Programming the Agent. Runnable example: examples/agent-in-pipeline.

⚙️ Installation & Configuration

Installation Guide: pip, the install.sh script, Docker images, and Android (Termux/Proot).
Environment Variables & Overrides: every general environment variable.
LLM & Rate Limiter Configuration: LLM provider, token budgets, and agent behavior.

🤝 CI/CD Integration

See the CI/CD Integration Guide for examples with GitHub Actions, GitLab CI, and Bitbucket Pipelines.

🗺️ Documentation Directory

Zrb scales from a one-line zrb please to a hundred-node pipeline with an agent in the middle.

Here for the agent? Programming the Agent → Extending the LLM → Permission Policy.

Here to write pipelines? Tasks & Execution Lifecycle → CLI and Groups → Inputs.

Prefer copy-pasting a working example? See examples/.

docs/adr/ and docs/technical-specs/ are maintainer-facing design history, not part of the reading path below.

I. The Agent

Shaping zrb llm chat and the LLM task types.

Choosing Between Agent Harnesses — zrb llm chat vs Claude Code, opencode, DeepSeek Harness, and Pi: when each is the right tool
Programming the Agent — the overview: every way to shape agent behavior in Python (tools, hooks, dynamic prompts, history processors, agent-as-pipeline-node)
Programming the Prompt — the ladder from a plain-string message up to a composed PromptManager; feeding a CmdTask's output into LLMTask/LLMChatTask
LLM Assistant & AI Tasks — interactive chat, LLMTask/LLMChatTask usage, troubleshooting
Extending the LLM — built-in tools, custom tools, sub-agents, model capabilities, context management
Custom UI — build a TUI, web/SSE, or chat-bot front end for LLMChatTask
Permission Policy System — fine-grained tool control & security gates
Sandbox — filesystem containment for LLM tool calls
Plan Mode — read-only discovery & strategy phase
LLMChatTask API Reference — builder API, TUI configuration
LLM Chat Request Lifecycle — end-to-end tour: CLI → agent run → UI → history persistence
Hook System (Claude Code Compatible)
MCP Support (Model Context Protocol)
LSP Support (Language Server Protocol)
Technical Spec: LLM Journal System
Claude Code Compatibility

II. Core Concepts

The foundational pillars of the framework.

Tasks & Execution Lifecycle
CLI and Groups
Inputs
Environments (Envs)
Session, Context & XCom
The @make_task Decorator — (advanced) full parameter reference
XCom Deep Dive — (advanced) patterns & pitfalls

III. Task Types

All task types available in Zrb, from basic to advanced.

Task & CmdTask — Python actions and shell commands
Custom Tasks — subclassing BaseTask with async patterns
Readiness: HttpCheck & TcpCheck
Automation: Triggers & Schedulers
File Ops: Scaffolder & RsyncTask
Built-in Helper Tasks (Git, Base64, UUID, HTTP, etc.)

IV. Advanced Topics

Web UI Guide
White-labeling: Create a Custom CLI
CI/CD Integration
Logging — Python logging vs. task-level context logging
Testing Zrb Tasks — mocking context, testing pipelines
Upgrading Guide

V. Contributing

Which pattern do I reach for? — lookup table for the pattern zrb expects when adding new code
Architecture & Conventions — for maintainers and contributors
Framework Conventions — the enforced R1–R12 rules
Maintainer Guide — start here to contribute code

VI. Configuration

Environment Variables & Overrides
LLM & Rate Limiter Configuration
LLM Component Collections — registries, managers, and the three configuration channels for skills, agents, hooks, prompts, and tools

VII. Examples

examples/ — runnable zrb_init.py for every topic above, grouped by category

VIII. Changelog

Changelog — full release history

🎥 Demo Video

Watch a video demonstration of Zrb in action:

💖 Support Zrb

If you find Zrb valuable, please consider showing your support:

🎉 Fun Fact

Did you know? Zrb is named after Zaruba, a powerful, sentient Madou Ring that acts as a guide and support tool in the Garo universe.

Madou Ring Zaruba (魔導輪ザルバ, Madōrin Zaruba) is a Madougu which supports bearers of the Garo Armor. (Garo Wiki | Fandom)

Madou Ring Zaruba on Kouga's Hand

Release files for zrb 3.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zrb 3.8.0
File	Size	Uploaded
zrb-3.8.0.tar.gz	2.3 MB	Sep 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for zrb 3.8.0
File	Interpreter	ABI	Platform	Reset
zrb-3.8.0-py3-none-any.whl 2.6 MB Sep 26, 2026	Python 3	none	any	Details

Total release size: 5.0 MB

Release files / zrb-3.8.0.tar.gz

Download URL	zrb-3.8.0.tar.gz
Size	2.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`5d51511d82d30749d98c95e7fe457edb4d39c975ada37154223d7fae01a6d411`
BLAKE2b-256 checksum How to use checksums	`870ae1bdaa2914a46b47b50fb9cc373db5831e2dbd2c9daf4539db7ec6955076`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.1 CPython/3.14.6 Linux/6.2.1-PRoot-Distro`

Release files / zrb-3.8.0-py3-none-any.whl

Download URL	zrb-3.8.0-py3-none-any.whl
Size	2.6 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`55e1f5472947dc05e50c8e5277e50a7a9a78c6bd7e0542c9eb46e8bbdb208152`
BLAKE2b-256 checksum How to use checksums	`30406e407cdb7104dc6052945043278c220b5829b53453076bcc9e005f9ea0de`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.1 CPython/3.14.6 Linux/6.2.1-PRoot-Distro`