GRALPH

GRALPH is a parallel AI coding runner that executes tasks across multiple agents in isolated git worktrees.

GRALPH reads a PRD, generates tasks with dependencies, and runs multiple agents in parallel using a DAG scheduler. Each task produces artifacts and commits work to isolated branches.

• DAG-based task scheduling with dependencies and mutexes
• Parallel execution by default (isolated git worktrees)
• Per-PRD run directories with all artifacts
• Automatic resume on re-run
• Stalled agent detection and automatic cleanup
• External failure detection (network, permissions, rate limits)
• Support for Claude Code, OpenCode, Codex, Cursor, and Gemini CLI
• Cross-platform: macOS, Linux, and Windows

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/FacuVCanale/gralph/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/FacuVCanale/gralph/main/install.ps1 | iex

The installer clones gralph and installs it as a Python CLI via pipx. Restart your terminal after installing.

Update:

gralph --update

• Python 3.10+
• git
• One of: Claude Code CLI, OpenCode CLI, Codex CLI, Cursor (agent in PATH), or Gemini CLI (gemini in PATH)
• Optional: gh (for creating PRs)

• Install Gemini CLI: https://github.com/google-gemini/gemini-cli
• Ensure gemini is available in your PATH
• Complete Gemini CLI auth/config before running gralph --gemini

# 1. Install skills in your project
cd my-project
gralph --init

# 2. Generate a PRD from a feature description
gralph prd "Add user authentication with OAuth"

# Or create PRD.md manually (must include: prd-id: my-feature)

# 3. Run gralph
gralph

# Run with default configs
gralph

# Run with a specific engine
gralph --opencode
gralph --cursor
gralph --codex
gralph --gemini

# Run with an explicit provider order
gralph --providers claude,codex
gralph --providers codex,gemini,cursor

# Generate a PRD
gralph prd "Add dark mode toggle"
gralph --codex prd -o PRD.md "Refactor payment flow"
gralph --providers gemini,codex prd "Improve test reliability and CI logs"

# Run sequentially
gralph --sequential

# Limit parallelism
gralph --max-parallel 2

# Dry run (preview without executing)
gralph --dry-run

# Resume a previous run
gralph --resume my-feature

# Use a specific PRD file
gralph --prd features/auth.md

# Skip tests and linting
gralph --fast

# Create PRs per task instead of auto-merge
gralph --create-pr --draft-pr

# Tune timeouts
gralph --stalled-timeout 900 --external-fail-timeout 600

--providers is mutually exclusive with engine flags (--claude, --opencode, --codex, --cursor, --gemini). The first provider in the list becomes the primary engine for the run.

If no engine flag and no --providers are set, GRALPH defaults to primary engine claude and provider order claude,opencode,codex,cursor,gemini.

For Codex, GRALPH defaults to --dangerously-bypass-approvals-and-sandbox so agents can edit files reliably in worktrees. Set GRALPH_CODEX_SAFE=1 (or GRALPH_CODEX_DANGEROUS=0) to force sandboxed mode.

Generate a PRD from a feature description using the prd subcommand:

gralph prd "Add user authentication with OAuth"
gralph --codex prd "Implement dark mode toggle"
gralph --gemini prd "Improve test reliability and CI logs"
gralph prd -o PRD.md "Refactor payment flow"

The subcommand inherits the engine from the parent (--claude, --opencode, --codex, --cursor, --gemini, or --providers). When using --providers, the first provider is used for PRD generation.

Generated PRDs are expected to include:

• Repository Structure Plan (define target directories/files before coding)
• Testing Requirements (automated tests required for implementation work)
• Documentation Requirements (explicit README.md and docs updates)
• Definition of Done (code + tests + docs + structure alignment)

PRD.md must include a prd-id line:

# PRD: My Feature

prd-id: my-feature

## Introduction
...

GRALPH generates tasks.yaml automatically from PRD.md.

version: 1
branchName: gralph/feature-name
tasks:
  - id: TASK-001
    title: "First task description"
    completed: false
    dependsOn: []
    mutex: []
    touches: []
    mergeNotes: ""
  - id: TASK-002
    title: "Second task"
    completed: false
    dependsOn: ["TASK-001"]
    mutex: ["db-migrations"]
    touches: ["src/db/schema.py"]

Valid mutex names: db-migrations, lockfile, router, global-config, and contract:* (dynamic pattern).

1. Install gralph (see Install)
2. cd into your project and run gralph --init
3. Generate a PRD: gralph prd "your feature" (or create PRD.md manually with prd-id: your-feature)
4. Run gralph (or gralph --opencode, etc.)
5. GRALPH creates artifacts/prd/<prd-id>/ with tasks.yaml
6. Tasks run in parallel using the DAG scheduler
7. Re-run anytime to resume (auto-detects existing run)
8. Use --resume <prd-id> to resume a different PRD

Each PRD run creates artifacts/prd/<prd-id>/:

• PRD.md - Copy of the PRD
• tasks.yaml - Generated task list
• progress.txt - Progress notes
• reports/<TASK_ID>.json - Task reports
• reports/<TASK_ID>.log - Task logs

GRALPH uses these skills (installed with --init):

• prd - Generate PRDs with prd-id
• ralph - Convert PRDs to tasks
• task-metadata - Validate tasks.yaml
• dag-planner - Plan task execution
• parallel-safe-implementation - Safe parallel coding
• merge-integrator - Merge branches
• semantic-reviewer - Review integrated code

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

PRs and issues welcome. Keep changes small and update tests/docs when adding features.

MIT

Inspired by Ralph, which pioneered autonomous AI coding loops.