Claude
2d4ead1e3f
CLI tool that decomposes big coding tasks into self-contained chunks, each with a ready-to-paste prompt including codebase context, targeted instructions, and dependency tracking. Supports phase, component, and manual decomposition strategies. https://claude.ai/code/session_01Fzv8baXnEVVhnrffAb3Ucc
120 lines
3.4 KiB
Markdown
120 lines
3.4 KiB
Markdown
# 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
|