# Cleave

Recursive task decomposition for Claude Code. Split complex directives along domain boundaries, execute in parallel, reunify with conflict detection.

## Etymology

"Cleave" holds contradictory meanings: to split apart AND to hold fast together. This duality captures the tool's essence—we cleave tasks into independent pieces, then cleave the results back into a unified whole.

## Installation

Both the CLI tool and Claude Code skill are required for full functionality.

### Option 1: pipx (Recommended)

Install in isolated environment with automatic skill installation:

```bash
# Install from PyPI
pipx install styrene-cleave

# Install the skill (creates symlink or copy as needed)
cleave install-skill

# Verify
cleave --help
```

**Updates:**
```bash
pipx upgrade styrene-cleave
cleave install-skill  # Auto-detects and updates stale installations
```

### Option 2: pip

```bash
# Install from PyPI
pip install styrene-cleave

# Install the skill
cleave install-skill

# Verify
cleave --help
```

### Option 3: Development (Editable)

```bash
# Clone the repo
git clone git@github.com:styrene-lab/cleave.git ~/projects/cleave

# Install in editable mode
pip install -e ~/projects/cleave

# Install the skill
cleave install-skill

# Verify
cleave --help
```

**Updates:**
```bash
cd ~/projects/cleave && git pull
cleave install-skill  # Updates if version changed
```

### Windows Users

On Windows 11, `cleave install-skill` will:
- Try to create a symlink (requires Developer Mode or admin privileges)
- Automatically fall back to directory copy if symlink fails
- Track version and auto-update on upgrades

To enable symlinks (optional, for better performance):
1. Open Settings → System → For developers
2. Enable "Developer Mode"
3. Run `cleave install-skill` again

### Interactive TUI (Optional)

Cleave includes an interactive terminal UI for task decomposition. This requires additional dependencies:

```bash
# TUI with Claude backend (default)
pipx install styrene-cleave[tui]

# TUI with local inference only (Ollama, vLLM, llama.cpp)
pipx install styrene-cleave[tui-local]

# All features
pipx install styrene-cleave[full]
```

Launch the TUI:
```bash
cleave tui [directory]  # Launch in current directory or specified path
```

#### TUI Features
- **Chat interface** with Claude Agent SDK integration
- **Multi-line input** with history navigation (Up/Down arrows)
- **Live streaming** of LLM responses
- **Tool use display** with syntax highlighting
- **Session management** with persistent history
- **CALF file support** for directive management
- **Retro CRT theme** with purple accents

#### Keyboard Shortcuts
- `Enter` - Submit message
- `Shift+Enter` - New line in input
- `Up/Down` - Navigate input history
- `Ctrl+L` - Clear chat
- `Escape` - Cancel operation
- `Tab/Shift+Tab` - Navigate between panels
- `q` - Quit

#### Backend Configuration

Configure backends in `~/.cleave/settings.yaml`:

```yaml
# Active backend
backend: claude  # or: ollama, openai, vllm, llamacpp

# Backend-specific settings
backends:
  claude:
    default_model: claude-sonnet-4-20250514

  ollama:
    base_url: http://localhost:11434/v1
    default_model: qwen2.5-coder:7b

  openai:
    base_url: https://api.openai.com/v1
    api_key_env: OPENAI_API_KEY
    default_model: gpt-4o
```

Manage settings via CLI:
```bash
cleave config show              # Display current settings
cleave config set backend ollama  # Switch to Ollama backend
cleave config path              # Show settings file location
```

## Usage

### Within Claude Code

Invoke via `/cleave` in any Claude Code session:

```
/cleave

Implement user authentication with JWT tokens, ensuring backwards
compatibility with existing session-based auth. Include migration
path and tests.
```

Claude will:
1. Assess complexity
2. Split into 2-3 child tasks if needed
3. Execute children (parallel or sequential)
4. Reunify results with conflict detection

### CLI Commands

```bash
# Assess complexity of a directive
cleave assess --directive "Add user auth with JWT"

# Match against known patterns
cleave match --directive "Add Stripe payments"

# Initialize workspace for manual execution
cleave init --directive "Add auth" --children '["Backend", "Frontend"]'

# Detect conflicts between task results
cleave conflicts --results ".cleave/0-task.md,.cleave/1-task.md"

# Reunify completed tasks
cleave reunify --workspace .cleave
```

## Concepts

### Complexity Assessment

**Formula**: `complexity = (1 + systems) × (1 + 0.5 × modifiers)`

- **Systems**: Distinct architectural boundaries (UI, API, DB, external services)
- **Modifiers**: State coordination, error handling, concurrency, security, etc.

If `complexity > threshold`, the directive gets cleaved.

### Splitting Strategy

- **Binary (2)**: Clean frontend/backend or data/logic seams
- **Ternary (3)**: Multi-layer stacks (UI/API/DB)
- **Never 4+**: Coordination overhead exceeds benefits

### Workspace Structure

```
.cleave/
├── manifest.yaml      # Intent, ancestry, children, assessment
├── siblings.yaml      # Sibling coordination, file claims
├── 0-task.md          # Child 0 task file
├── 1-task.md          # Child 1 task file
├── metrics.yaml       # Telemetry
├── merge.md           # Reunification report
└── review.md          # Adversarial review
```

Workspaces are auto-generated with unique names based on the directive to prevent collisions:

- `cleave init -d "Add JWT auth" -c '["A", "B"]'` → `.cleave-add-jwt-auth/`
- `cleave init -d "Optimize queries" -c '["X", "Y"]'` → `.cleave-optimize-queries/`

If a workspace already exists, a numeric suffix is added (`.cleave-add-jwt-auth-2/`).
To override, use `--output` explicitly: `cleave init -d "..." -c '[...]' -o .cleave-custom/`

All `.cleave*` directories are gitignored; they are ephemeral artifacts consumed by `cleave reunify`
and should be removed once the workspace is closed.

### Conflict Detection

Four conflict types detected during reunification:

1. **File Overlap** - Multiple children modified same file
2. **Decision Contradiction** - Incompatible choices (Redis vs Memcached)
3. **Interface Mismatch** - Different signatures for same function
4. **Assumption Violation** - Child assumption contradicts sibling decision

## Configuration

### Modes

- **Lean** (default): Terse output, fast-path assessment
- **Robust**: Verbose reasoning, sequential thinking for all assessments

### Flags

- `--no-tdd`: Skip TDD workflow instructions in task files
- `--no-review`: Skip adversarial review during reunification
- `--infer-permissions`: Detect required bash permissions upfront

## Documentation

### Guides

- **[Getting Started](docs/guides/getting-started.md)** - Installation, first cleave session, reading reports
- **[TUI Usage](docs/guides/tui-usage.md)** - Interactive terminal UI guide
- **[Advanced Patterns](docs/guides/advanced-patterns.md)** - Custom patterns, calibration, multi-model workflows
- **[Contributing](docs/guides/contributing.md)** - Development setup, running tests, submitting PRs

### Reference

- **[CALF Format](docs/calf-format.md)** - Complete specification for `.calf` directive files
- **[Architecture Overview](docs/architecture/overview.md)** - System components and data flow
- **[Backend Interface](docs/architecture/backend-interface.md)** - Implementing custom TUI backends
- **[Assessment Pipeline](docs/architecture/assessment-pipeline.md)** - Pattern matching and complexity calculation

### Examples

- **[Basic Usage](examples/basic-usage/)** - Simple and complex directive examples
- **[Patterns](examples/patterns/)** - Real-world pattern examples with documentation
  - [Authentication System](examples/patterns/authentication-system.md)
  - [Database Migration](examples/patterns/database-migration.md)
  - [External Integration](examples/patterns/external-integration.md)
- **[TUI Examples](examples/tui/)** - Backend configuration, session workflow, keyboard shortcuts
- **[CLI Workflows](examples/cli/)** - Shell scripts for assessment, reunification, metrics

## Requirements

- Python 3.11+
- Claude Code CLI (for skill usage)
- Sequential Thinking MCP server (recommended for complex assessments)

## License

MIT
