# 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

```bash
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:

```markdown
## 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.