Iriai Build Tool

0.6.6 · active · verified Tue Apr 21

Iriai Build (version 0.6.6) is an AI agent orchestration Command Line Interface (CLI) designed for planning, implementing, and shipping software features. It streamlines the development workflow by managing multi-agent pipelines directly from the terminal or via a Slack bridge. The tool integrates with the `claude` CLI as its underlying execution engine, allowing for sequential planning phases (PM, Designer, Architect, Plan Compiler) and parallel implementation across multiple teams. Key differentiators include its state-machine driven feature lifecycle, signal-based agent communication via the filesystem, multi-team coordination capabilities, and flexible budget tiers for controlling model usage and concurrency. It offers both interactive terminal and asynchronous Slack modes for user decisions and updates. As a pre-1.0 tool, its release cadence is likely agile, with ongoing feature development and potential for breaking changes.

Common errors

```
Command 'claude' not found
```
cause The `claude` CLI executable is not installed, not in the system's PATH, or `CLAUDE_BIN` environment variable is incorrectly set.

fix Install the `claude` CLI (refer to its documentation for specific instructions). Verify its accessibility by running `which claude`. If needed, configure the `CLAUDE_BIN` environment variable or run `iriai-build setup` to explicitly set its path.
```
Node.js version 16.x detected. Iriai Build requires Node.js >= 18.
```
cause The system's active Node.js version is older than the minimum requirement of 18.

fix Upgrade your Node.js installation to version 18 or newer. If using `nvm`, run `nvm install 18 && nvm use 18`.
```
Slack tokens are not configured. Cannot launch Slack bridge.
```
cause Attempting to use Slack-related commands (`slack`, `transfer-to-slack`) without providing the necessary `slack_app_token` and `slack_bot_token`.

fix Run `iriai-build setup` interactively and provide the required Slack App and Bot tokens. Alternatively, set the `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` environment variables before running the commands.
```
Permission denied: access to ~/.iriai/config.json
```
cause The user executing `iriai-build` commands lacks sufficient write permissions for the `~/.iriai` directory or the `config.json` file within it.

fix Check the file permissions for the `~/.iriai` directory and `~/.iriai/config.json`. Ensure the user has read and write access (e.g., `chmod 700 ~/.iriai` and `chmod 600 ~/.iriai/config.json`).

Warnings

breaking This package is pre-1.0 (currently 0.6.6) and is subject to frequent breaking changes in its API, command structure, and configuration schemas. Users should expect to review release notes for each update.
Fix: Always check the latest README and release notes when upgrading. Consider pinning minor versions (e.g., `^0.6.0`) or specific patch versions if stability is critical for your workflow.
gotcha Iriai Build requires the `claude` CLI to be installed globally and available in the system PATH, or its path must be explicitly configured via the `CLAUDE_BIN` environment variable or during `iriai-build setup`. Without it, agent execution will fail.
Fix: Install the `claude` CLI (e.g., `npm install -g claude` if it's an npm package, or follow its specific installation instructions) and ensure it's accessible. Run `which claude` to confirm its path, then configure `CLAUDE_BIN` or run `iriai-build setup`.
gotcha The default budget tier is `unrestricted`, which can incur significant API costs due to extensive Opus model usage and parallel agent execution. Monitor your Claude API usage closely.
Fix: Configure a stricter budget tier using `--budget econ` or `--budget budget` when running commands, or set it persistently via `iriai-build setup` or the `IRIAI_BUDGET` environment variable.
gotcha Features initiated and progressing in terminal mode do not automatically sync to Slack for asynchronous collaboration. To transition a terminal-initiated feature to Slack, the `transfer-to-slack` command is required.
Fix: Use `iriai-build transfer-to-slack` for existing features. Ensure `slack_app_token` and `slack_bot_token` are configured via `iriai-build setup` or corresponding environment variables before attempting Slack operations.
gotcha Node.js version 18 or higher is a mandatory prerequisite. Using older Node.js versions may lead to runtime errors, compatibility issues, or unexpected behavior.
Fix: Upgrade your Node.js installation to version 18 or higher. Tools like `nvm` (Node Version Manager) can facilitate easy switching and management of Node.js versions (e.g., `nvm install 18 && nvm use 18`).

Install

npm install iriai-build npm
yarn add iriai-build yarn
pnpm add iriai-build pnpm

Imports

iriai-build (CLI executable)
wrong:
```
import { iriaiBuild } from 'iriai-build'
```
correct:
```
npm install -g iriai-build
iriai-build [command] [options]
```
This package is a global CLI tool designed for command-line execution, not for programmatic `import` into a JavaScript/TypeScript project. Interactions occur via its subcommands after global installation.
iriai-build launch (subcommand)
wrong:
```
import { launch } from 'iriai-build'
```
correct:
```
iriai-build launch "Implement user login feature"
```
CLI subcommands are the primary interaction points. Attempting to import them as functions or objects in code will result in an error as they are not exposed programmatically.
iriai-build setup (subcommand)
wrong:
```
const config = require('iriai-build').setup();
```
correct:
```
iriai-build setup
```
Configuration is managed interactively through the CLI's `setup` command, which writes to `~/.iriai/config.json`. There is no programmatic API for setup.

Quickstart

Demonstrates the global installation of iriai-build, interactive configuration, and launching a complete AI-driven feature development cycle via the `launch` command.

#!/bin/bash

# --- Prerequisites ---
# Ensure Node.js >= 18 is installed.
# Ensure 'claude' CLI is installed globally and configured (e.g., with API key).
# If 'claude' is an npm package, install it: npm install -g claude
# Otherwise, follow its specific installation instructions.

# --- Installation ---
npm install -g iriai-build

# --- Configuration ---
# Run interactive setup for tokens, tool paths, budget tier, and preferences.
# This will save configuration to ~/.iriai/config.json
iriai-build setup

# --- Launching a Feature ---
# Define a simple feature description for the AI agents.
FEATURE_DESCRIPTION="Add a 'Privacy Policy' page with standard legal text and a contact email link."

# Launch the full feature development cycle using the 'launch' command.
# This will initiate planning, implementation, and review gates interactively.
# Be prepared for a potentially long-running process with multiple prompts.
# Ensure you are in your project's root directory when running for a real project.

iriai-build launch "$FEATURE_DESCRIPTION"

echo "Iriai-build launched for feature: '$FEATURE_DESCRIPTION'."
echo "Follow the interactive prompts in your terminal to guide the agents."

view raw JSON →