ralphkit

Agent pipes and loops for Claude Code. Inspired by the ralph loop.

• Loop — plan-driven iteration. Creates a structured plan, then iterates one item at a time until all are complete.
• Pipe — linear sequence. Each step runs once, passing context forward via handoff files.

Install

pip install ralphkit

With uv:

uv tool install ralphkit

Quick Start

Write a task file that clearly specifies what needs to be done, then run it:

ralphkit build feature.md       # plan-driven loop: plan → build → review
ralphkit fix bug.md             # diagnose → fix → verify
ralphkit research question.md   # explore → synthesize → report
ralphkit plan feature.md        # analyze → design document
ralphkit big-swing epic.md      # research → plan → build → review → fix → verify

Task files should contain a well-specified description of the work to be done: the goal, relevant context, constraints, and acceptance criteria. The built-in workflows own the process. Your task file should describe the work itself, not tell ralphkit how to plan, diagnose, review, or verify it.

Starter task-file templates live in templates/tasks/. Copy the one that matches the command you want to run and fill in the sections.

For custom workflows, use the generic primitives with a YAML config:

ralphkit pipe task.md --config pipe.yaml
ralphkit loop task.md --config loop.yaml

Use ralphkit <command> --help to see all available options.

Task Files

Each built-in command expects a different kind of brief, but they all follow the same rule: describe the task, not the workflow. ralphkit already knows the flow for build, fix, research, plan, and big-swing.

Use the starter templates in templates/tasks/:

• build.md for feature implementation
• fix.md for bug reports
• research.md for codebase research
• plan.md for implementation design docs
• big-swing.md for large, multi-phase work

In practice, a good task file usually covers:

• Goal or problem statement
• Relevant context and existing behavior
• Constraints and non-goals
• Acceptance criteria
• Deliverables or output filename, if you care about a specific artifact name

How It Works

Loop

   Setup             Planning                 Loop (iterate)               Cleanup
┌──────────┐    ┌─────────────────┐    ┌──────────────────────────┐    ┌──────────────┐
│ step 1   │    │ planner         │    │ Read tickets.json        │    │ step 1       │
│ step 2   │    │ → tickets.json  │    │ Work on next item        │    │ ...          │
│ ...      │    └─────────────────┘    │ Update tickets.json      │    └──────────────┘
└──────────┘                           │ All done? → COMPLETE     │
                                       │ More items? → loop       │
                                       └──────────────────────────┘

The planner agent reads the task and breaks it into discrete items in tickets.json. Each loop iteration works on exactly one item, marks it done, and appends learnings to progress.md. Cleanup runs after the loop exits regardless of outcome.

Pipe

┌────────┐    ┌────────┐    ┌────────┐
│ step 1 │───>│ step 2 │───>│ step 3 │──> done
└────────┘    └────────┘    └────────┘
     │             │             │
     └── handoff ──┘── handoff ──┘

Each step runs once. Context flows forward through named handoff files (e.g., handoff__analyze__to__plan.md).

Config

The --config flag is required for pipe and loop primitives. The named subcommands (build, fix, etc.) have built-in configs.

Loop config

max_iterations: 10
default_model: opus
plan_model: sonnet

loop:
  - step_name: worker
    task_prompt: "Read {state_dir}/tickets.json, find the next incomplete item, and implement it."
    system_prompt: "You are a WORKER in a RALPH LOOP..."

Pipe config

default_model: opus

pipe:
  - step_name: analyze
    task_prompt: "Analyze the codebase: {task}"
    system_prompt: "Perform a thorough code analysis."

  - step_name: implement
    task_prompt: "Implement the plan from the analysis."
    system_prompt: "Write the code described in the plan."
    model: sonnet

Each step requires step_name, task_prompt, and system_prompt. Optional: model (per-step override), handoff_prompt (pipe only). See configs/ for complete examples.

Background Jobs

Any command accepts --host to run as a background job via tmux:

ralphkit build task.md --host local   # local tmux session
ralphkit build task.md --host mini    # remote host (SSH config name)
ralphkit big-swing epic.md --host mini --working-dir /path/to/project

The --host flag takes an SSH config name directly — no additional config needed. Remote jobs run via uvx, so ralphkit doesn't need to be pre-installed on the remote host.

ralphkit jobs [--host NAME]             # list active jobs
ralphkit logs JOB_ID [--host NAME]      # view job logs (-F to follow)
ralphkit cancel JOB_ID [--host NAME]    # cancel a running job
ralphkit runs                           # list past completed runs

Requirements

• Claude Code CLI (claude must be on your PATH)
• Python 3.10+
• tmux (for --host background jobs only)