Rut Documentation

Rut is the macOS workbench that lets you orchestrate Gemini, Claude Code, and OpenAI Codex agents in visual DAG workflows. Chain their strengths, watch them run in real isolated terminals, and ship code faster than ever.

🚀

Quickstart

Create your first multi-agent workflow in under 5 minutes.

⌨️

CLI Reference

Complete guide to rut-cli commands and options.

⌘

Keyboard Shortcuts

Master the app with keyboard shortcuts.

Quickstart

Get started with Rut in a few simple steps.

1. Install rut-cli

Terminal

npm install -g rut-cli

# Or run directly with npx
npx rut-cli --help

2. Initialize a project

Required: The --repo flag is required to specify the code repository path.

Terminal

rut init my-project --repo /path/to/your/code

3. Add nodes with different agents

Terminal

# Add a Codex node (default agent)
rut add "Fix the bug in auth.ts" --codex --title "Bug Fix"

# Add a Claude node that depends on the previous one
rut add "Refactor the handlers" --claude --upstream "Bug Fix" --pass-context

# Add a Gemini node for testing
rut add "Write unit tests" --gemini --upstream "Refactor"

4. View and run the workflow

Terminal

# List nodes
rut ls -v

# Run the workflow
rut run

Or open the Rut app — your project appears automatically in the visual canvas!

rut CLI Installation

npm (recommended)

Terminal

npm install -g rut-cli

npx (no installation)

Terminal

npx rut-cli --help

File Locations

`~/Library/Application Support/com.sounart.Noded/Projects/`	Project files
`~/.rut/config.json`	Configuration
`~/.rut/current`	Current project pointer

Project Management

`rut init <name> --repo <path>`

Initialize a new project. The --repo flag is required.

Terminal

rut init refactor-project --repo /path/to/code

`rut projects`

List all projects.

Terminal

rut projects

`rut open <project>`

Switch to a different project.

Terminal

rut open my-project

Node Operations

`rut add <prompt>`

Add a new node to the current project.

Flag	Short	Description
`--codex`	`-x`	Use OpenAI Codex (default)
`--claude`	`-c`	Use Anthropic Claude Code
`--gemini`	`-g`	Use Google Gemini
`--mcp`	`-m`	Use MCP Provider
`--title`		Set node title
`--upstream`		Connect to parent node(s)
`--pass-context`		Pass context from upstream

Example

rut add "Analyze the codebase" --gemini --title "Analysis"
rut add "Implement changes" --claude --upstream "Analysis" --pass-context

`rut ls`

List all nodes in the current project. Use -v for verbose output.

`rut show <node>`

Show details of a specific node (by title or ID).

`rut rm <node>`

Remove a node and its connections.

`rut connect <from> <to>`

Create a connection between two nodes.

Terminal

rut connect "Analysis" "Implementation" --pass-context

Execution

`rut run [node]`

Run the full workflow or a specific node. Agents spawn in isolated terminal sessions.

Terminal

# Run entire workflow
rut run

# Run specific node
rut run "Analysis"

Configuration

`rut config show`

Display current configuration settings.

`rut config set <key> <value>`

Set a configuration value.

`rut config set-secret <key>`

Set a secret value (prompted securely).

Keyboard Shortcuts

Master the Rut app with these keyboard shortcuts.

Canvas Actions

Shortcut	Action
`⌘N`	Add new CLI Agent node
`⌘⏎`	Connect selected nodes
`⌘R`	Run selected nodes
`⌫`	Delete selection
`Esc`	Clear selection

Window Management

Shortcut	Action
`⇧⌘N`	New window
`⇧⌘]`	Next tab
`⇧⌘[`	Previous tab

Debugging

Shortcut	Action
`⌘D`	Toggle debug logs

Agent Types

Rut supports multiple AI agent CLIs that can be mixed in the same workflow.

Codex

OpenAI

The default agent. OpenAI's Codex CLI for code generation and editing tasks.

--codex or -x

Claude Code

Anthropic

Anthropic's Claude Code CLI. Great for complex reasoning and code review.

--claude or -c

Gemini

Google

Google's Gemini CLI. Excellent for research, analysis, and multi-modal tasks.

--gemini or -g

MCP Provider

Custom

Model Context Protocol provider. Connect to Postgres, Puppeteer, or custom APIs.

--mcp or -m

Node Types

Different node types serve different purposes in your workflow.

Type	Description	Use Case
CLI Agent	Runs prompts through an AI CLI	Code generation, refactoring, analysis
Reviewer	Merges context from multiple parents	Combining outputs from parallel branches
Pause	Human-in-the-loop checkpoint	Code review gates, deployment approval
Provider	Direct provider API access	Custom model configurations, MCP tools