claude-smart-usage/README.md

Claude Task Chunker

Save Claude Code usage on large codebases. Two files you drop into any repo.

The Problem

You ask Claude Code to fix errors or add a feature to a big codebase. It spends half your usage just reading files to find the problem, then runs out before it finishes the fix.

The Solution

Two files you copy into your project repo:

File	What it does
CLAUDE.md	Claude reads this automatically every session. It teaches Claude to scan first, stay focused, commit often, and leave a handoff note if usage runs low.
scan.py	A script Claude runs itself to find errors. It calls your project's linters, tests, and type checkers — zero AI tokens used.

Setup (one time per project)

1. Copy CLAUDE.md and scan.py into the root of your project repo
2. Edit the "Project-Specific Commands" section in CLAUDE.md if needed
3. Commit them

cp /path/to/claude-task-chunker/CLAUDE.md /path/to/your-project/
cp /path/to/claude-task-chunker/scan.py /path/to/your-project/
cd /path/to/your-project
git add CLAUDE.md scan.py
git commit -m "Add Claude Code efficiency tools"

That's it. You never touch these files again.

How You Use It

Your workflow doesn't change. You type in Claude Code exactly like before.

Finding and fixing errors

You:     "Find and fix the errors in this codebase"

Claude (because it read CLAUDE.md) will automatically:

1. Run python scan.py — gets linter/test/type errors in seconds
2. Read only the files with errors
3. Fix them
4. Commit

Without CLAUDE.md, Claude would read file after file trying to find the problems, burning through your usage.

Big features

You:     "Add OAuth2 authentication with login, logout, and role-based access"

Claude (because it read CLAUDE.md) will automatically:

1. Plan which files to change before coding
2. Work through the plan, committing after each piece
3. If usage runs low, commit what's done and create .claude-handoff.md

If it does run out, your next session you just say:

You:     "Continue the work described in .claude-handoff.md"

And Claude picks up right where it left off — no wasted tokens re-discovering what was already done.

What scan.py 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

Customizing CLAUDE.md

The CLAUDE.md file has a section at the bottom for project-specific commands. Edit it to match your project:

## Project-Specific Commands

# Run tests:        pytest -x
# Lint:             ruff check . --fix
# Build:            docker compose build
# Type check:       mypy src/

You can also add any other instructions you want Claude to follow in every session — coding style, architecture decisions, files to avoid, etc.

What's in this repo

CLAUDE.md      — Template to copy into your projects
scan.py        — Scanner script to copy into your projects
README.md      — You're reading it

The claude_task_chunker/ directory contains an optional CLI tool (ctc) for manually planning and tracking chunks from the terminal. Most users won't need it — the CLAUDE.md + scan.py approach handles everything automatically.