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, fix errors across a 10,000-line codebase — 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

Two things working together:

1. ctc scan — Runs linters, tests, and pattern matching on your codebase without using any AI tokens. Finds the errors so Claude doesn't have to read 10,000 lines to find them itself.
2. ctc plan — Breaks big tasks into self-contained chunks with ready-to-paste prompts for Claude Code.
3. ctc init — Drops a CLAUDE.md into your repo that teaches Claude Code to be usage-efficient automatically.

Install

# Clone this repo, then:
pip install -e .

Quick Start: The Workflow

Step 1: Set up your project (one time)

cd /path/to/your/big-project
ctc init

This creates a CLAUDE.md in your project that teaches Claude Code to work efficiently — chunk its own work, commit often, and not waste tokens exploring.

Step 2: Find errors fast (no AI needed)

ctc scan
# or with a specific focus:
ctc scan "authentication is broken"

This runs your project's linters, tests, and type checkers automatically. It detects what kind of project you have (Python, Node, Rust, Go) and runs the right tools. The output goes to .claude-chunks/scan_results.md.

Step 3: Open Claude Code and paste the results

Open Claude Code connected to your repo as normal. Then:

Fix the errors in .claude-chunks/scan_results.md

Claude reads the pre-scanned results and goes straight to fixing — no wasted tokens reading 10,000 lines to find the bugs.

Step 4: For big tasks, plan chunks first

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

This creates numbered prompt files in .claude-chunks/prompts/. Each one is a self-contained session:

ctc next       # see the next chunk's prompt
ctc next -c    # copy it to clipboard

Open Claude Code, paste the prompt, let it work, then:

ctc done 1     # mark chunk 1 complete
ctc next       # get chunk 2

Your Actual Workflow

Here's what this looks like day-to-day:

You:     cd my-big-project
You:     ctc scan                          # 10 seconds, finds 3 errors
You:     [open Claude Code]
You:     "Fix the errors in .claude-chunks/scan_results.md"
Claude:  [reads the file, fixes the 3 errors, done in one session]

For big features:

You:     ctc plan "migrate database from MySQL to Postgres" -s phase
You:     ctc next -c                       # copies chunk 1 prompt
You:     [open Claude Code, paste]
Claude:  [does chunk 1: research & plan, commits]
You:     ctc done 1
You:     ctc next -c                       # copies chunk 2 prompt
You:     [paste into Claude Code — same session or new one]
Claude:  [does chunk 2: core implementation, commits]
You:     ctc done 2
         ... and so on

Commands

Command	What it does
ctc init	Add CLAUDE.md to your project (teaches Claude to be efficient)
ctc scan	Find errors with linters/tests (no AI tokens used)
ctc scan "description"	Same, but adds your description to the output prompt
ctc plan <task>	Break a big task into chunks
ctc plan <task> -s component	Chunk by directory/module instead of phase
ctc plan <task> -s manual --chunks-file chunks.txt	Use your own chunk list
ctc status	See progress on current plan
ctc next	Print the next chunk's prompt
ctc next -c	Copy it to clipboard
ctc done <id>	Mark a chunk as complete
ctc show <id>	View a specific chunk's prompt

What ctc scan Detects

It auto-detects your project type and runs the right tools:

Project	What it runs
Python	pytest, ruff, mypy, syntax check
Node/TypeScript	npm/yarn test, eslint, tsc --noEmit
Rust	cargo check, cargo test --no-run
Go	go build, go vet, go test
Any	grep for TODO/FIXME/HACK/BUG markers

Decomposition Strategies

phase (default)

Breaks work into: Research & Plan -> Core Implementation -> Tests -> Integration & Cleanup.

component

One chunk per top-level directory. Good when changes are spread across independent modules.

manual

You write a text file with one chunk 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

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

Tips

• Always ctc scan before asking Claude to fix errors — saves huge amounts of usage
• ctc init once per project — the CLAUDE.md stays in the repo and works every session
• 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
• Commit CLAUDE.md to your repo — it benefits every Claude Code session in that project