Ralph

AI development automation: sandboxed devcontainers, task management, autonomous task execution.

Quick Start

Requires uv and Docker.

# 1. Install ai-sbx globally (from monorepo root)
uv tool install --from ./sandbox ralph-sandbox

# 2. One-time system setup (Docker images, groups, directories)
ai-sbx init global

# 3. Initialize your project
cd /your/project
ai-sbx init project

# 4. Create a devcontainer worktree and start working
ai-sbx worktree create "implement user auth"

# 5. After monorepo changes — rebuild images, reinstall CLI, sync config
ai-sbx sync

Run ai-sbx help for the full command reference.

Packages

Package	Directory	CLI Command	Description
ralph-sandbox	sandbox/	ai-sbx	Devcontainer management for AI agents
ralph-tasks	tasks/	ralph-tasks-web	Neo4j-backed task management + MCP server
ralph-cli	ralph-cli/	ralph	Autonomous task execution with API recovery

Configuration

Directory	Description
claude/	Claude Code hooks, commands, skills
codex/	Codex CLI configuration

ai-sbx Commands

Command	Description
ai-sbx init global	One-time system setup (images, groups, directories)
ai-sbx init project [path]	Initialize project with .devcontainer/
ai-sbx init update [path]	Regenerate .env and docker-compose.override.yaml from ai-sbx.yaml
ai-sbx worktree create <desc>	Create git worktree + start devcontainer
ai-sbx worktree list	List worktrees with container status
ai-sbx worktree connect [name]	Connect to existing worktree
ai-sbx worktree remove [name]	Remove worktree (optionally delete branch)
ai-sbx sync	Rebuild images, reinstall CLI tools, sync config
ai-sbx image build	Build Docker images
ai-sbx image list	List images and status
ai-sbx doctor	Diagnose and fix common issues
ai-sbx upgrade	Upgrade to latest version
ai-sbx notify	Start desktop notification watcher

Development

Setup

uv sync --all-packages

Tests

uv run pytest                    # All tests
uv run pytest tasks/tests/       # ralph-tasks only
uv run pytest sandbox/tests/     # ralph-sandbox only
uv run pytest ralph-cli/tests/   # ralph-cli only

Linting

uv run ruff check .
uv run ruff format --check .

Architecture

• uv workspace — single lockfile, shared dev dependencies
• Flat layout — tasks/ralph_tasks/, not tasks/src/ralph_tasks/
• Per-package tests — each package has its own tests/ directory
• --import-mode=importlib — avoids name collisions in monorepo test collection