Skip to main content
Glama
README.md
<p align="center">
  <a href="https://irrigator.dev"><img src="docs/mascot.png" alt="Irrigator mascot" width="146"></a>
</p>

<h1 align="center">Irrigator</h1>

<p align="center"><strong>Durable local workflows for the coding agents you already use.</strong></p>

<p align="center">
  Plan the graph. Run in parallel. Inspect or resume from your terminal.<br>
  Explicit state, retries, and spending boundaries for local agent work.
</p>

<p align="center">
  <a href="https://irrigator.dev/"><img src="https://img.shields.io/badge/website-irrigator.dev-fcc830?style=for-the-badge" alt="See the Irrigator homepage"></a>
</p>

<p align="center">
  <a href="docs/platform-support.md"><img src="https://img.shields.io/badge/go-%E2%89%A51.26.7-00ADD8?logo=go&logoColor=white" alt="Go 1.26.7 or later"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
  <a href="https://deepwiki.com/grainulation/irrigator"><img src="https://img.shields.io/badge/docs-DeepWiki-1f6feb" alt="Docs on DeepWiki"></a>
</p>

<p align="center">
  <a href="https://github.com/grainulation/irrigator/actions/workflows/platforms.yml"><img src="https://github.com/grainulation/irrigator/actions/workflows/platforms.yml/badge.svg?branch=main" alt="macOS and Linux CI"></a>
  <a href="https://github.com/grainulation/irrigator/actions/workflows/windows-wsl.yml"><img src="https://github.com/grainulation/irrigator/actions/workflows/windows-wsl.yml/badge.svg?branch=main" alt="Windows (WSL) CI"></a>
</p>

<p align="center">
  <a href="#try-it-without-credentials">Quick start</a> ·
  <a href="docs/first-run.md">First run</a> ·
  <a href="#plugins">Plugins</a> ·
  <a href="docs/agent-setup.md">Agent setup</a> ·
  <a href="docs/index.md">Documentation</a> ·
  <a href="CHANGELOG.md">Changelog</a>
</p>

---


## What it adds

Irrigator runs coding agents in parallel while keeping results, retries and
spending evidence on disk. Use the CLI directly or through **Claude Code,
Codex and Antigravity plugins**. Inspect the work and resume from your terminal.

| Capability | What it gives you |
| --- | --- |
| **Durable execution** | Saved plans, attempts and accepted artifacts that survive interruptions. |
| **Coding cells** | One task per git worktree, with branches and objective checks to review. |
| **Bounded delegation** | Explicit task graphs, worker concurrency and provider limits. |
| **Recovery decisions** | Uncertain external work stays visible and is never silently replayed. |
| **Terminal review** | `status --watch`, `graph`, `review tui` and a read-only MCP view. |

## Try it without credentials

Requires **Go 1.26.7+**, `make` and a POSIX shell. Development and CI pin Go 1.27.2.
From a source checkout:

```sh
git clone https://github.com/grainulation/irrigator.git
cd irrigator
make build
./irrigator doctor
./irrigator demo
```

The demo uses mock workers, needs no credentials and makes no model calls.
Each invocation creates a fresh run directory and prints inspection commands.
For your own plan, follow the [first-run guide](docs/first-run.md).

To install from this checkout, run `make install PREFIX="$HOME/.local"` and add
`$HOME/.local/bin` to `PATH`. Installation copies the CLI; agent plugins and
provider tools have their own setup. CLI archives and their installation checks
are described in [runtime releases](docs/runtime-release.md).

Homebrew users can install the stable CLI from this repository's [tap](docs/homebrew.md):

```sh
brew tap grainulation/irrigator https://github.com/grainulation/irrigator
brew install grainulation/irrigator/irrigator
irrigator demo
```

The stable formula installs a pinned release archive and does not need Go.
For a development source build, use `brew install --HEAD grainulation/irrigator/irrigator`.
See the [Homebrew guide](docs/homebrew.md) for supported platforms, upgrades and checks.

### Ask your agent to start

Give Claude Code, Codex or Antigravity this prompt from the checkout:

```text
Read README.md and AGENTS.md in the Irrigator repository. Build ./irrigator with make build,
run ./irrigator agents and ./irrigator demo, and report the exit codes and final status lines.
Tell me which routes below this machine can run. Ask before any model-backed or paid run.
```

| Route | What it does | Needs | Cost and limits |
| --- | --- | --- | --- |
| **1. Mock demo and starter plan** | `demo`, `init`, `plan`, `apply --backend mock` | Local CLI | No model calls or API spend |
| **2. Local models** | Managed tasks using [Ollama](docs/managed-ollama.md) | CLI, Ollama and a local model | Local compute; no API spend |
| **3. Managed CLI profiles** | Turn/helper graphs via `claude:MODEL`, `codex:MODEL`, `agy:MODEL` | CLI and authenticated provider | Cost tracking by default; explicit enforced-budget profiles available |
| **4. Coding cells** | [`irrigator code`](docs/coding-cells.md), with branches to review | CLI, git repo and an agent CLI | Per-cell timeout; Claude USD cap; Codex/agy cost unknown, no USD cap |

Real providers use your account or local compute. New managed plans track
estimates without blocking when costs are unavailable; tracking thresholds warn.
Enforced budgets control admission and reservations and can still be overrun by
a provider. Unknown cost never means free execution. See
[cost tracking and enforced budgets](docs/execution-profiles.md#best-effort-cost-tracking).

## Put it to work

Start with a plan, validate it, then choose a backend explicitly:

```sh
./irrigator init --out plan.json
./irrigator plan plan.json
./irrigator apply plan.json --run runs/first --backend mock
./irrigator status runs/first
```

Use new plan filenames and run directories. For repository changes, coding
cells accept `--task ID=PROMPT` and `--verify ID=COMMAND`; results land on local
branches for review. A verification timeout or exit 77 leaves the result uncertain, as does a
successful check that changes the worktree or Git identity. See [coding cells](docs/coding-cells.md)
for setup, spending limits and recovery.

For graphs that grow during execution, choose
[recursive spawning](docs/swarm-shapes.md) or
[managed turns and helpers](docs/turn-shapes.md). These have separate execution
rules; worker concurrency is independent of graph size.

## Plugins

Install the `irrigator` runtime separately, then follow
[agent setup](docs/agent-setup.md) for your host:

| Host | Setup |
| --- | --- |
| Claude Code | [Claude Code plugin](docs/claude-plugin.md) |
| Codex | [Codex plugin or manual workflow](docs/codex-plugin.md) |
| Antigravity | [Antigravity plugin](docs/agent-setup.md#antigravity) |
| Other MCP hosts | [`irrigator mcp`](docs/mcp.md) |

The plugins share [Markdown skills](skills) and the local CLI under the host's
normal execution permissions. [Host integration](docs/host-integration.md)
covers installation and discovery checks; static package checks alone do not
establish that a host can load or invoke a plugin.

## Explore the docs

| Guide | Start here for… |
| --- | --- |
| [First run](docs/first-run.md) | Your own plan, provider selection and inspection. |
| [Coding cells](docs/coding-cells.md) | Parallel repository tasks and verification commands. |
| [Workflow composition](docs/workflow-composition.md) | Reusable graphs and artifact contracts. |
| [Terminal workspace](docs/terminal-workspace.md) | Swarm dashboard and local review. |
| [Recovery](docs/recovery.md) | Interrupted calls, retries and execution authority. |
| [Architecture](docs/architecture.md) | Source layout, package layers and durable state. |
| [Compatibility](docs/compatibility.md) | The supported 1.x interfaces and saved-run formats. |
| [Documentation index](docs/index.md) | Accounting, providers, command references and more. |

## Verification and limits

The CLI supports **macOS and Linux**. Windows users run the Linux build inside
[WSL 2](docs/windows-wsl.md); native Windows is planned.
[Platform support](docs/platform-support.md) records the tested configurations.

Worktrees keep concurrent checkouts apart; they are not a host sandbox.
Approvals record a decision bound to a specific head and never merge changes.
See [SECURITY.md](SECURITY.md) for the local trust model.

CI runs builds, mock workflows, race tests and package checks. Native host and
live-provider acceptance are separate. Run the development gates with:

```sh
make acceptance
make lint
```

The [verification matrix](verification/README.md) details their scope, including
integration tests. [Contributing](CONTRIBUTING.md) covers setup and changes;
[choosing a tool](docs/alternatives.md) explains the tradeoffs.
See the [changelog](CHANGELOG.md) for releases and the
[release checklist](docs/versioned-release.md) for artifact promotion.

---

<p align="center">
  Built by <a href="https://grainulation.com">Grainulation</a> ·
  <a href="LICENSE">MIT licensed</a> ·
  <a href="https://github.com/grainulation/irrigator/issues">Issues & ideas</a>
</p>