Introduction

The open-source toolchain for agentic AI — orchestrate agents, convert API specs, merge everything cleanly.

What is ruah?

ruah is an open-source toolchain that solves a specific problem: what happens when multiple AI agents edit the same codebase at the same time?

Without coordination, agents overwrite each other's work, create merge conflicts, and produce broken code. ruah prevents this by giving each agent its own isolated workspace (a git worktree), tracking which files each agent is allowed to touch, and merging their results back together in the right order.

It also converts API specifications (OpenAPI, Swagger, GraphQL, Postman, HAR) into tool definitions that agents can actually call — so your agents can interact with any API without manual wiring.

The ecosystem

Six standalone tools, one CLI, optional orchestrator. Each tool works in a repo where no other ruah package is installed.

Package	What it does	npm
`@ruah-dev/cli`	Top-level router — `ruah <tool> …`	published
`@ruah-dev/guard`	Can I trust the agent not to do damage — in any harness, with proof?	coming soon
`@ruah-dev/verify`	Did the agent actually finish?	coming soon
`@ruah-dev/opt`	Where did my tokens go?	coming soon
`@ruah-dev/watch`	Can I show someone what this session did?	coming soon
`@ruah-dev/eval`	Same task — which executor wins, and what did it cost?	coming soon
`@ruah-dev/conv`	How do I make this API agent-sized?	published
`@ruah-dev/orch`	Optional multi-agent orchestration	published
`@ruah-dev/schema`	Canonical Workflow / Task / Trace / Policy types	coming soon

You can use them independently or together. Install the CLI and it discovers whatever is installed (or siblings in this workspace).

Claude Code plugin

ruah map shows the architecture of any repo, code and cloud infrastructure, as a map inside Claude Code. It is a plugin, not an npm package: /plugin marketplace add ruah-dev/ruah-map, then /plugin install ruah@ruah.

Quick Start

# Install the CLI
pnpm add -g @ruah-dev/cli

# Initialize in any git repo
ruah init

# Create your first isolated task
ruah task create my-feature \
  --files "src/**" \
  --executor claude-code \
  --prompt "Implement the feature"

# Start it
ruah task start my-feature

How It Fits Together

ruah          ← top-level CLI
├── guard     ← policies for tool calls
├── verify    ← machine-runnable definition of done
├── opt       ← token / cost profiler
├── watch     ← static HTML replay
├── eval      ← same task, N executors
├── conv      ← spec → curated agent tools
└── orch      ← optional orchestration (tasks, workflows)

Requirements

Node.js 18.0.0 or higher
Git repository (for orchestration features)
Zero runtime dependencies — the orchestrator has none, the converter needs only yaml

Next Steps

Getting Started — install and run your first workflow
Orchestration — deep dive into task isolation and claims
Conversion — convert API specs to agent tools