styrene-cleave 0.8.0

Recursive task decomposition for Claude Code - domain-aware splitting and reunification

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:

# Install from PyPI
pipx install styrene-cleave

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

# Verify
cleave --help

Updates:

pipx upgrade styrene-cleave
cleave install-skill  # Auto-detects and updates stale installations

Option 2: pip

# Install from PyPI
pip install styrene-cleave

# Install the skill
cleave install-skill

# Verify
cleave --help

Option 3: Development (Editable)

# Clone the repo
git clone [e-mail]: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:

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:

# 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:

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:

# 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:

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

# 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

Development

Running Tests

The test suite includes unit tests, integration tests, and TUI tests.

# Install development dependencies
pip install -e ".[dev,full]"

# Run all tests
pytest

# Run with coverage
pytest --cov=cleave --cov-report=html

# Run specific test files
pytest tests/test_assessment.py
pytest tests/test_tui_integration.py
pytest tests/test_probe_integration.py

# Run only unit tests (fast)
pytest tests/ -k "not integration"

# Run only integration tests
pytest tests/test_tui_integration.py tests/test_probe_integration.py

# Run with verbose output
pytest -v

# Run async tests (requires pytest-asyncio)
pytest tests/test_tui_integration.py -v

Integration Test Coverage

TUI Integration Tests (tests/test_tui_integration.py):

• App launch and shutdown lifecycle
• Backend connection management (Claude SDK)
• Message send/receive with streaming support
• Tool use display and formatting
• Session persistence and history
• Cancellation token handling
• Input history navigation
• CALF file loading and execution
• Error handling for auth failures and invalid input

Probe Integration Tests (tests/test_probe_integration.py):

• Real project probing (uses cleave codebase as test subject)
• Stack detection for Python, TypeScript, JavaScript, Go, Rust
• Infrastructure detection (Docker, Kubernetes, Terraform)
• Relevant file discovery based on directive keywords
• Context-aware question generation
• Pattern matching integration
• Edge cases and error handling

Test Requirements

Integration tests require:

• pytest>=8.0
• pytest-asyncio>=0.23.0 (for async TUI tests)
• textual>=0.47.0 (for TUI tests)
• claude-agent-sdk>=0.1.0 (for SDK integration tests)

Install all test dependencies:

pip install -e ".[dev,full]"

Requirements

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

License

MIT