# Claude Task Chunker (`ctc`)

Break large coding tasks into self-contained chunks for efficient Claude Code sessions. Stop running out of usage mid-task.

## The Problem

You ask Claude Code to make a big change — add auth, refactor a module, migrate a database — and it runs out of usage halfway through. You're left with half-finished work and no easy way to pick up where you left off.

## The Solution

`ctc` decomposes large tasks into independent, self-contained chunks. Each chunk is a complete prompt you can paste into a fresh Claude Code session. It includes just enough context for Claude to work without needing the prior conversation.

## Install

```bash
pip install -e .
```

## Usage

### 1. Plan — decompose a task

```bash
ctc plan "Add OAuth2 authentication with login, logout, and RBAC"
```

This analyzes your codebase and creates a set of numbered chunks in `.claude-chunks/prompts/`.

### 2. Execute — one chunk at a time

```bash
# See what's next
ctc next

# Or copy it straight to clipboard
ctc next -c

# Paste the prompt into Claude Code and let it work
```

### 3. Track — mark chunks as done

```bash
ctc done 1
ctc status
```

### 4. Repeat until the full task is complete

```bash
ctc next    # get the next chunk
# paste into Claude Code
ctc done 2  # mark it complete
ctc next    # and so on
```

## Decomposition Strategies

### `phase` (default)
Breaks work into standard phases: Research & Plan → Core Implementation → Tests → Integration & Cleanup. Best for most tasks.

```bash
ctc plan "Migrate from REST to GraphQL" -s phase
```

### `component`
Groups work by directory/module. Best when changes are spread across independent components.

```bash
ctc plan "Add input validation everywhere" -s component
```

### `manual`
You define the chunks yourself in a text file, one per line.

```bash
# chunks.txt
Set up database models for users and roles
Build registration and login API endpoints
Add JWT middleware and session management
Build role-based access control decorators
Add frontend login/logout pages
```

```bash
ctc plan "Add user auth" -s manual --chunks-file chunks.txt
```

## Commands

| Command | Description |
|---------|-------------|
| `ctc plan <task>` | Decompose a task into chunks |
| `ctc status` | Show progress on current plan |
| `ctc next` | Print the next chunk's prompt |
| `ctc next -c` | Copy next chunk's prompt to clipboard |
| `ctc done <id>` | Mark a chunk as complete |
| `ctc show <id>` | Show a specific chunk's prompt |

## How It Works

1. **Analyzes** your codebase structure (languages, key files, directory layout)
2. **Decomposes** the task using the chosen strategy
3. **Generates** self-contained prompts with codebase context, targeted instructions, file lists, and verification steps
4. **Tracks** progress so you always know what's done and what's next

Each generated prompt tells Claude Code:
- What the codebase looks like (summary, not full contents)
- Exactly what to do in this chunk
- Which files to read and modify
- What depends on what
- How to verify the work is correct

## Tips

- **Start with `phase` strategy** — it works well for most tasks
- **Use `manual` for complex tasks** — you know your codebase best; write chunks that make sense for your architecture
- **Keep chunks independent** — the less each chunk depends on others, the cleaner the handoff
- **Add `.claude-chunks/` to `.gitignore`** — it's working state, not source code