splitty

Pipes-and-filters orchestration for chunk-level analysis with sub-agents.

What it does

You hand splitty a corpus and a goal. Splitty designs a pipeline (a YAML DAG of filters), splits the corpus into chunks, and walks the DAG one stage at a time. Each stage runs a sub-agent over its assigned chunks, writes outputs to disk, and the next stage consumes those outputs. Every branch of the DAG ends in a terminal filter that unions the branch's outputs into a final result.

Design at a glance

corpus.txt
   │
   ▼
[chunker]──► chunks/0001.txt … chunks/N.txt
   │
   ▼
┌──────────────────────────────────┐
│  pipeline.yaml (DAG of stages)   │
│                                  │
│   stage A (map, per-chunk)       │
│        │                         │
│        ▼                         │
│   stage B (map, per-chunk)       │
│        │                         │
│        ├──► stage C (reduce)     │
│        └──► stage D (reduce)     │
│              │      │            │
│              ▼      ▼            │
│         stage E (terminal)       │
└──────────────────────────────────┘
              │
              ▼
         result.md

The orchestrator is Claude itself, driven by the /splitty-run skill: read state, ask Python for the next batch of pending steps, dispatch parallel Task() calls (one sub-agent per pending step), mark them done, repeat until all branches close.

Stage types

| Type | Cardinality | Closes a branch? | |------------|----------------------------|------------------| | map | one sub-agent per chunk | no | | reduce | one sub-agent over inputs | no | | gate | filter chunks by condition | no (no agent) | | loop | repeat a stage to fixed point | no | | terminal | one sub-agent unioning a branch | yes |

A pipeline is valid only if every leaf in the DAG is a terminal stage.

Layout

splitty/
├── .claude-plugin/plugin.json
├── skills/
│   ├── splitty/SKILL.md             # /splitty — full lifecycle (design → run)
│   ├── splitty-design/SKILL.md      # design pipeline.yaml from a request
│   └── splitty-run/SKILL.md         # execute an existing pipeline.yaml
├── agents/
│   └── splitty-filter.md            # substrate sub-agent (general-purpose)
├── commands/
│   ├── splitty.md
│   ├── splitty-design.md
│   └── splitty-run.md
├── scripts/
│   ├── splitty.py                   # single-entry CLI: init, next, mark, union, etc.
│   └── lib/                         # chunker, validator, state machine
├── pipelines/examples/
│   ├── map-reduce-summary.yaml
│   ├── classify-and-extract.yaml
│   └── fan-out-fan-in.yaml
└── docs/pipeline-schema.md

Install

Splitty is distributed through the public RedJay marketplace. Inside Claude Code:

/plugin marketplace add JoshuaRamirez/claude-code-plugins
/plugin install splitty@RedJay

Or from the CLI:

claude plugin marketplace add JoshuaRamirez/claude-code-plugins
claude plugin install splitty@RedJay

The plugin registers one sub-agent (splitty-filter), three skills (splitty, splitty-design, splitty-run), and three slash commands (/splitty, /splitty-design, /splitty-run).

Quickstart

/splitty extract every named entity from notes/*.md and produce a deduplicated catalog

Splitty designs a pipeline, writes it to .splitty/runs/<run-id>/pipeline.yaml, then drives the run. You can also hand it an existing pipeline:

/splitty-run path/to/my-pipeline.yaml --input corpus.txt

Run state

Each run is fully on disk under .splitty/runs/<run-id>/:

.splitty/runs/<run-id>/
├── pipeline.yaml          # frozen copy of the pipeline used
├── input/                 # original input(s)
├── chunks/                # chunked input
├── state.json             # execution state (pending / running / done per step)
├── outputs/<stage-id>/    # per-step outputs
└── result.md              # final unioned output

Runs are resumable: kill the conversation, pick up later by pointing /splitty-run at the same run-id.