claude-smart-usage/README.md

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

pip install -e .

Usage

1. Plan — decompose a task

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

# 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

ctc done 1
ctc status

4. Repeat until the full task is complete

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.

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

component

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

ctc plan "Add input validation everywhere" -s component

manual

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

# 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

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