---
name: ko-cli
description: Hand off complex coding tasks to KO CLI for heavy refactoring, multi-file debugging, and architectural changes. Use when facing: (1) Multi-file refactoring across dozens of files, (2) Deep debugging requiring multiple iterations, (3) Code architecture rewrites, (4) Performance optimization across a codebase. KO CLI runs in a dedicated environment with isolated credits, saving expensive model tokens on brute-force iteration. Requires KO subscription (~$20/mo, ~1000 credits).
---

# KO CLI Skill

KO CLI is a paid code-offloading service that handles heavy lifting coding tasks in isolation. Instead of burning expensive model tokens on iterative refactoring or debugging, hand off the work to KO's environment.

## When to Use KO CLI

**Handoff when:**
- Multi-file refactoring (10+ files affected)
- Deep debugging with multiple iteration loops
- Code architecture rewrites
- Performance profiling and optimization
- Automated code migrations
- Large-scale test generation

**Don't handoff when:**
- Single-file edits or small changes
- Quick bug fixes or patches
- Explanation/learning tasks
- Design review or planning phases

## Quick Start

1. **Verify KO is configured:**
   - API key set in `KO_API_KEY` environment variable
   - Subscription active with available credits

2. **Describe the task:**
   - Specify files involved
   - Explain the goal (refactor, debug, optimize)
   - Provide context (architecture, constraints)

3. **Monitor progress:**
   - KO processes the task in its environment
   - Returns diff summary and logs
   - Review changes before applying

4. **Apply changes:**
   - Review the diff
   - Merge back to your codebase
   - Test thoroughly

## Configuration

### Environment Setup

Set the KO API key in your OpenClaw `.env`:

```bash
KO_API_KEY=your-ko-api-key-here
KO_BASE_URL=https://api.ko.ai  # Default, may vary
```

### Credit Management

- **Cost per task**: Varies by complexity (typically 10-100 credits)
- **Monthly quota**: ~1000 credits ($20 subscription)
- **Check balance**: Use `ko-cli balance` to see remaining credits

## Usage Patterns

### Pattern 1: Large Refactoring

```
"Refactor the authentication module across users/ and auth/ directories.
Target: Move from callback-based to async/await.
Constraints: Maintain backward compatibility for 3 major versions."
```

KO will:
- Scan all affected files
- Plan the refactoring
- Apply changes with proper testing
- Return a complete diff

### Pattern 2: Performance Debugging

```
"Profile this codebase for performance bottlenecks.
Focus: Database query optimization.
Context: We have 50M user records, typical query scans 1M rows."
```

KO will:
- Run profiling in its environment
- Identify hot spots
- Propose optimizations with diffs
- Estimate performance gains

### Pattern 3: Code Migration

```
"Migrate from Jest to Vitest.
Scope: All test files in tests/ directory.
Requirements: Keep test output format identical."
```

KO will:
- Convert test files
- Update configuration
- Validate test compatibility
- Return ready-to-merge changes

## Advanced Options

### Dry-run Mode

Test changes without committing credits:

```bash
ko-cli run --dry-run --task "refactor authentication"
```

### Priority/Speed

Trade credits for faster processing:

```bash
ko-cli run --priority=high --task "urgent bug fix"
```

### Custom Environment

Specify runtime or dependencies:

```bash
ko-cli run --runtime=node18 --task "refactor"
```

## Reference

See [KO_REFERENCE.md](references/KO_REFERENCE.md) for:
- Complete CLI command list
- Credit system details
- Supported languages and frameworks
- API rate limits and quotas

See [INTEGRATION.md](references/INTEGRATION.md) for:
- OpenClaw <-> KO workflow
- How to review and apply diffs
- Rollback procedures
- Cost optimization tips

## Troubleshooting

**"Insufficient credits"**
- Check `ko-cli balance`
- Upgrade your subscription or wait for monthly refresh

**"Task failed"**
- Review logs: `ko-cli logs <task-id>`
- Check if task scope was too large
- Consider breaking into smaller subtasks

**"Changes look wrong"**
- Use `--dry-run` to preview without committing
- Contact KO support with task ID
